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INTRODUCTION 


This manual describes the programming features of the ICON/UXV system. It provides neither a general 
overview of the ICON/UXV system nor details of the implementation of the system. 

Not all commands, features, and facilities described in this manual are available in every ICON/UXV 
system. The entries not applicable for a particular hardware line will have an appropriate caveat 
stamped in the center of the mast of an entry. Also, programs m facilities being phased out will be 
marked as “Obsolescent” on the top of the entry. When in doubt, consult your system’s administrator. 

This manual is divided into four sections, some containing inter-filed sub-classes: 

2. System Calls. 

3. Subroutines: 

3C. C and Assembler Library Routines 
3S. Standard I/O Library Routines 
3M. Mathematical Library Routines 
3X. Miscellaneous Routines 
3F. FORTRAN Library Routines 

4. File Formats. 

5. Miscellaneous Facilities. 

Section 2 (System Calls) describes the entries into the ICON/UXV system kernel, including the C 
language interface. 

Section 3 (Subroutines) describes the available subroutines. Their binary versions reside in various sys¬ 
tem libraries in the directories /lib and /usr/lib. See *nfro(3) for descriptions of these libraries and the 
files in which they are stored. 

Section 4 (File Formats) documents the structure of particular kinds of files; for example, the format of 
the output of the link editor is given in a.out(4), Excluded are files used by only one command (for 
example, the assembler’s intermediate files). In general, the C language struct declarations correspond¬ 
ing to these formats can be found in the directories /usr/include and /usr/include/sys. 

Section 5 (Miscellaneous Facilities) contains a variety of things. Included are descriptions of character 
sets, macro packages, etc. 

Each section consists of a number of independent entries of a page or so each. The name of the entry 
appears in the upper corners of its pages. Entries within each section are alphabetized, with the excep¬ 
tion of the introductory entry that begins each section (also section 3 is in alphabetical order by 
suffixes). Some entries may describe several routines, commands, etc. In such cases, the entry appears 
only once, alphabetized under its “major” name. 

All entries are based on a common format, not all of whose parts always appear: 

The NAME part gives the name(s) of the entry and briefly states its purpose. 

The SYNOPSIS part summarizes the use of the program being described. A few conventions are 
used, particularly in Section 2 (System Calls): 

Boldface strings are literals and are to be typed just as they appear. 

Italic strings usually represent substitutable argument prototypes and program names found 
elsewhere in the manual (they are underlined in the typed version of the entries). 

Square brackets [] around an argument prototype indicate that the argument is optional. 
When an argument prototype is given as “name” or “file”, it always refers to a file name. 

A vertical bar j between arguments indicates a selection argument, i.e. only one of the argu¬ 
ments separated by vertical bars is to be used. 
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Ellipses . •. are used to show that the previous argument prototype may be repeated. 

A final convention is used by the commands themselves. An argument beginning with a minus 
—, plus -f, or equal sign * is often taken to be some sort of flag argument, even if it appears in 
a position where a file name could appear. Therefore, it is unwise to have files whose names 
begin with —, +, or ■». 

The DESCRIPTION part discusses the subject at hand. 

The EXAMPLE(S) part gives example(s) of usage, where appropriate. 

The FILES part gives the file names that are built into the program. 

The SEE ALSO part gives pointers to related information. 

The DIAGNOSTICS part discusses the diagnostic indications that may be produced. Messages that 
are intended to be self-explanatory are not listed. 

The WARNINGS part points out potential pitfalls. 

The BUGS part gives known bugs and sometimes deficiencies. Occasionally, the suggested fix is also 
described. 

A table of contents precedes Section 2. On each index line, the title of the entry to which that line 
refers is followed by the appropriate section number in parentheses. This is important because there is 
considerable duplication of names among the sections, arising principally from commands that exist only 
to exercise a particular system call. 

On most systems, all entries are available on-line via the man(l) command (see Section 1 of the 
ICON/UXV User Reference Manual ). 
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2. System Calls 


access(2).determine accessibility of a file 

acct(2)...enable or disable process accounting 

alarm(2).set a process alarm clock 

brk(2).change data segment space allocation 

chdir(2)...change working directory 

chmod(2).. . . change mode of file 

chown(2).change owner and group of a file 

chroot(2).change root directory 

close(2).. . . close a file descriptor 

creat(2).. . • • create a new file or rewrite an existing one 

dup(2).duplicate an open file descriptor 

execl(2).execute a file 

execle(2).see execl(2) 

execlp(2). see execl(2) 

execv(2) . ...» .see execl(2) 

execve(2).see execl(2) 

execvp(2).see execl(2) 

exit(2). terminate process 

fcntl(2). file control 

fork(2)...create a new process 

fstat(2) . . • « ..see stat(2) 

getegid(2).see getuid(2) 

geteuid(2).see getuid(2) 

getgid(2).see getuid(2) 

getpgrp(2).see getpid(2) 

getpid(2).get process, process group, and parent process IDs 

getppid(2).see getpid(2) 

getuid(2).get real user, effective user, real group, and effective group IDs 

intro(2).introduction to system calls and error numbers 

ioctl(2).control device 

kill(2).send a signal to a process or a group of processes 

link(2).link to a file 

lseek(2).move read/write file pointer 

mknod(2).make a directory, or a special or ordinary file 

mount(2).mount a file system 

msgctl(2) ... . . message control operations 

msgget(2). get message queue 

msgop(2).message operations 

nice(2) . change priority of a process 

open(2) .. open for reading or writing 

ovride(2).set/clear hardware OVRIDE bit 

pause(2).suspend process until signal 

pipe(2) . . . ..create an interprocess channel 

plock(2).lock process, text, or data in memory 

profil(2).execution time profile 

ptrace(2).. • • • ..process trace 

read(2) .read from file 

sbrk(2).. • see brk(2) 

semctl(2).semaphore control operations 

semget(2) • • • ..get set of semaphores 
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semop(2)....semaphore operations 

setgid(2)...see setuid(2) 

setpgrp(2).set process group ID 

setuid(2).set user and group IDs 

shmctl(2).shared memory control operations 

shmget(2).get shared memory segment 

shmop(2).shared memory operations 

signal(2).specify what to do upon receipt of a signal 

stat(2).....get file status 

stime(2).....set time 

swrite(2).synchronous write on a file 

sync(2)...update super-block 

time(2).....get time 

times(2).get process and child process times 

ulimit(2).get and set user limits 

umask(2).set and get file creation mask 

umount(2).unmount a file system 

uname(2)..get name of current UNIX system 

unlink(2).. . remove directory entry 

ustat(2)...get file system statistics 

utime(2).set file access and modification times 

wait(2).wait for child process to stop or terminate 

write(2).write on a file 

_exit(2).see exit(2) 

3. Subroutines 

a64l(3c).convert between long integer and base-64 ASCII string 

abort(3c).generate an IOT fault 

abort(3f).terminate Fortran program 

abs(3c).return integer absolute value 

abs(3f).Fortran absolute value 

acos(3f)...Fortran arccosine intrinsic function 

acos(3m). see sin(3m) 

aimag(3f).Fortran imaginary part of complex argument 

aint(3f).Fortran integer part intrinsic function 

alog(3f) ... . ..see log(3f) 

alogl0(3f).see logl0(3f) 

-amax0(3f).see max(3f) 

amaxl(3f). see max(3f) 

amin0(3f).see min(3f) 

aminl(3f).see min(3f) 

amod(3f)..see mod(3f) 

and(3f)...Fortran Bitwise Boolean functions 

anint(3f).Fortran nearest integer functions 

asctime(3c).see ctime(3c) 

asin(3f)...Fortran arcsine intrinsic function 

asin(3m). see sin(3m) 

assert(3x).verify program assertion 

atan(3f).Fortran arctangent intrinsic function 

atan(3m). see sin(3m) 

atan2(3f).Fortran arctangent intrinsic function 

atan2(3m).see sin(3m) 

atof(3c).see strtod(3c) 
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&toi(3c).see strtol(3c) 

&tol(3c).see strtol(3c) 

bsearch(3c).binary search a sorted table 

btest(3f).see ior(3f) 

cabs(3f).see abs(3f) 

calloc(3c).. ..see malloc(3c) 

calloc(3x).. . see malloc(3x) 

ccos(3f).see cos(3f) 

ceil(3m).see floor(3m) 

cexp(3f).see exp(3f) 

char(3f).see int(3f) 

clearerr(3s). see ferror(3s) 

clock(3c)...report CPU time used 

clog(3f)..see log(3f) 

cmplx(3f) .see int(3f) 

conjg(3f).Fortran complex conjugate intrinsic function 

cos(3f).Fortran cosine intrinsic function 

cos(3m). see sin(3m) 

cosh(3f).Fortran hyperbolic cosine intrinsic function 

cosh(3m)..see sinh(3m) 

crypt(3c).generate DES encryption 

csin(3f) .see sin(3f) 

csqrt(3f) .see sqrt(3f) 

ctermid(3s)..generate file name for terminal 

ctime(3c).convert date and time to string 

curses(3x) . . . ..CRT screen handling and optimization package 

cuserid(3s).get character login name of the user 

dabs(3f).... ..see abs(3f) 

dacos(3f). see acos(3f) 

dasin(3f).see asin(3f) 

datan(3f)...see atan(3f) 

datan2(3f) • . . ..*.see atan2(3f) 

dble(3f).see int(3f) 

dcmplx(3f).. . . see int(3f) 

dconjg(3f).see conjg(3f) 

dcos(3f)...see cos(3f) 

dcosh(3f).. see cosh(3f) 

ddim(3f) .see dim(3f) 

dexp(3f).see exp(3f) 

dial(3c).establish an out-going terminal line connection 

dim(3f).positive difference intrinsic functions 

dimag(3f).see aimag(3f) 

dint(3f)...see aint(3f) 

directory:(3x) . . . opendir, readdir, telldir, seekdir, rewinddir, closedir directory operations 

dlog(3f)...see log(3f) 

dlogl0(3f).see logl0(3f) 

dmaxl(3f)...see max(3f) 

dminl(3f).see min(3f) 

dmod(3f).see mod(3f) 

dnint(3f). see anint(3f) 

dprod(3f).double precbion product intrinsic function 

drand48(3c).generate uniformly distributed pseudo-random numbers 

dsign(3f) ...see sign(3f) 
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dsin(3f).. . ♦ . ..see sin(3f) 

dsinh(3f).... ..see sinh(3f) 

dsqrt(3f)...see sqrt(3f) 

dtan(3f)...see tan(3f) 

dtanh(3f)......see tanh(3f) 

ecvt(3c).convert floating-point number to string 

edata(3c)...see end(3c) 

encrypt(3c)..see crypt(3c) 

end(3c).last locations in program 

endgrent(3c)...see getgrent(3c) 

endpwent(3c)...see getpwent(3c) 

endutent(3c) .. • . .see getutent(3c) 

erand48(3c).*.. see drand48(3c) 

erf(3m).error function and complementary error function 

erfc(3m).see erf(3m) 

errno(3c).....see perror(3c) 

etext(3c)...see end(3c) 

exp(3f).Fortran exponential intrinsic function 

exp(3m).exponential, logarithm, power, square root functions 

fabs(3m)...see fioor(3m) 

fclose(3s).close or flush a stream 

fcvt(3c).. ... see ecvt(3c) 

fdopen(3s).see fopen(3s) 

feof(3s).see ferror(3s) 

ferror(3s).stream status inquiries 

fflush(3s) . . ... . . see fclose(3s) 

fgetc(3s).see getc(3s) 

fgetgrent(3c) .see getgrent(3c) 

fgetpwent(3c)...see getpwent(3c) 

fgets(3s) .see gets(3s) 

fileno(3s) ......see ferror(3s) 

float(3f). ... see int(3f) 

floor(3m).floor, ceiling, remainder, absolute value functions 

fmod(3m).. . see floor(3m) 

fopen(3s).open a stream 

fprintf(3s)..see printf(3s) 

fputc(3s).. . see putc(3s) 

fputs(3s).see puts(3s) 

fread(3s).. binary input/output 

free(3c). see malloc(3c) 

free(3x) .see malloc(3x) 

freopen(3s).see fopen(3s) 

frexp(3c).manipulate parts of floating-point numbers 

fscanf(3s).see scanf(3s) 

fseek(3s).. reposition a file pointer in a stream 

ftell(3s). see fseek(3s) 

ftok(3c).standard interprocess communication package 

ftw(3c) .. walk a file tree 

fwrite(3s).see fread(3s) 

gamma(3m)...log gamma function 

gcvt(3c)...see ecvt(3c) 

getarg(3f).return Fortran command-line argument 

getc(3s).get character or word from a stream 
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getchar(3s) . 
getcwd(3c) . , 
getcnv(3c) . . 
getenv(3f) . , 
getgrent(3c) . 
getgrgid(3c) . 
getgrnam(3c) 
getlogin(3c) . 
getopt(3c) . 
getpass(3c) . 
getpw(3c) . . 
getpwent(3c) 
getpwnam(3c) 
getpwuid(3c) 
gets(3s) . * . 
gctutent(3c) . 
getutid(3c) . 
getutline(3c) 
getw(3s) . . 
gmtime(3c) 
gsignal(3c) . 
hcreate(3c) 
hdestroy(3c) 
hsearch(3c) . 
hypot(3m) . 
iabs(3f) • . 
iand(3f) . . 
iargc(3f) . . 
ibclr(3f) . . 
ibits(3f) . . 
ibset(3f) . . 
ichar(3f) . . 
idim(3f) . . 
idint(3f) . . 
idnint(3f) 
ieor(3f) ♦ . 
ifix(3f) ; . . 
index(3f) . . 
int(3f) • . . 
intro(3) . • 
ior(3f) . . . 
irand(3f) . 
isalnum(3c) . 
isalpha(3c) . 
isascii(3c) . 
isatty(3c) . 
iscntrl(3c) • 
isdigit(3c) . 
isgraph(3c) . 
ishft(3f) . . 
ishftc(3f) . . 
isign(3f) . . 
islower(3c) . 


. see getc(3s) 

. get path-name of current working directory 

.return value for environment name 

.... return Fortran environment variable 

.get group file entry 

. . . . ..see getgrent(3c) 

.see getgrent(3c) 

.get login name 

... get option letter from argument vector 

..read a password 

.get name from UID 

.get password file entry 

.see getpwent(3c) 

.. ... see getpwent(3c) 

• .get a string from a stream 

.access utmp file entry 

.see getutent(3c) 

.see getutent(3c) 

. see getc(3s) 

.see ctime(3c) 

.see ssignal(3c) 

..see hsearch(3c) 

.see hsearch(3c) 

.manage hash search tables 

.. • Euclidean distance function 

.see abs(3f) 

.see ior(3f) 

return the number of command line arguments 

.see ior(3f) 

.see ior(3f) 

.see ior(3f) 

.see int(3f) 

..see dim(3f) 

.see int(3f) 

• .see anint(3f) 

.see ior(3f) 

.see int(3f) 

.return location of Fortran substring 

.explicit Fortran type conversion 

• • • introduction to subroutines and libraries 

.. ... bit 

..random number generator 

. ...see isalpha(3c) 

.classify characters 

.see isalpha(3c) 

.. see ttyname(3c) 

.see isalpha(3c) 

.see isalpha(3c) 

.see isalpha(3c) 

.see ior(3f) 

.see ior(3f) 

...see sign(3f) 

.see isalpha(3c) 
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isprint(3c).see isalpha(3c) 

ispunct(3c). see isalpha(3c) 

isspace(3c).see is&lpha(3c) 

isupper(3c).see isalpha(3c) 

isxdigit(3c).see isalpha(3c) 

jO(3m). Bessel functions 

jl(3m).see j0(3m) 

jn(3m).see j0(3m) 

jrand48(3c).see drand48(3c) 

l3tol(3c).convert between 3-byte integers and long integers 

164a(3c)...see &64l(3c) 

lcong48(3c)..see drand48(3c) 

ldaclose(3x) . ...see ldclose(3x) 

ldahread(3x).read the archive header of a member of an archive file 

ldaopen(3x).. • • . see ldopen(3x) 

ldclose(3x) ...close a common object file 

ldexp(3c).....see frexp(3c) 

ldfhread(3x).read the file header of a common object file 

ldgetname(3x).retrieve symbol name for common object file symbol table entry 

ldlinit(3x).see ldlread(3x) 

ldlitem(3x).see ldlread(3x) 

ldlread(3x) .manipulate line number entries of a common object file function 

ldlseek(3x).seek to line number entries of a section of a common object file 

ldnlseek(3x).see ldlseek(3x) 

ldnrseek(3x). see ldrseek(3x) 

ldnshread(3x)...see ldshread(3x) 

ldnsseek(3x).see ldsseek(3x) 

ldohseek(3x).. seek to the optional file header of a common object file 

ldopen(3x).open a common object file for reading 

ldrseek(3x).seek to relocation entries of a section of a common object file 

ldshread(3x).read an indexed named section header of a common object file 

ldsseek(3x) .seek to an indexed named section of a common object file 

ldtbindex(3x).compute the index of a symbol table entry of a common object file 

ldtbread(3x).read an indexed symbol table entry of a common object file 

ldtbseek(3x).seek to the symbol table of a common object file 

len(3f)...return length of Fortran string 

lfind(3c). see lsearch(3c) 

lge(3f).string comparison intrinsic functions 

lgt(3f).see lge(3f) 

Ue(3f) .. • see lge(3f) 

llt(3f).see lge(3f) 

localtime(3c)...see ctime(3c) 

lockf(3c)...record locking on files 

log(3f).. Fortran natural logarithm intrinsic function 

log(3m).see exp(3m) 

logl0(3f) ..Fortran common logarithm intrinsic function 

logl0(3m)...see exp(3m) 

logname(3x).return login name of user 

longjmp(3c).....see setjmp(3c) 

lrand48(3c)...see drand48(3c) 

lsearch(3c).. linear search and update 

lshift(3f) .see and(3f) 

ltol3(3c).see 13tol(3c) 
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mallinfo(3x).see malloc(3x) 

malloc(3c).....main memory allocator 

malloc(3x)...fast main memory allocator 

mallopt(3x).see malloc(3x) 

matherr(3m)...error-handling function 

max(3f).Fortran maximum-value functions 

max0(3f).see max(3f) 

maxl(3f).see max(3f) 

mclock(3f).return Fortran time accounting 

memccpy(3c) . .memory operations 

memchr(3c).see memccpy(3c) 

memcmp(3c).see memccpy(3c) 

memcpy(3c)...see memccpy(3c) 

memset(3c)...see memccpy(3c) 

min(3f)...Fortran minimum-value functions 

min0(3f)...see min(3f) 

minl(3f).see min(3f) 

mktemp(3c).make a unique file name 

mod(3f) .Fortran remaindering intrinsic functions 

modf(3c) . . . . ....see frexp(3c) 

monitor(3c).prepare execution profile 

mrand48(3c) . . . .. see drand48(3c) 

mvbits(3f)...... see ior(3f) 

nint(3f).see anint(3f) 

nlist(3c).get entries from name list 

not(3f).see and(3f) 

not(3f).see ior(3f) 

nrand48(3c).see drand48(3c) 

or(3f)...see and(3f) 

pclose(3s) ..see popen(3s) 

perror(3c).system error messages 

plot(3x).graphics interface subroutines 

popen(3s).initiate pipe to/from a process 

pow(3m)...see exp(3m) 

printf(3s).*.print formatted output 

putc(3s).put character or word on a stream 

putchar(3s).see putc(3s) 

putenv(3c).change or add value to environment 

putpwent(3c).write password file entry 

puts(3s) . . . . ..put a string on a stream 

pututline(3c).... see getutent(3c) 

putw(3s).see putc(3s) 

qsort(3c)...quicker sort 

rand(3e).simple random-number generator 

rand(3f).see irand(3f) 

real(3f)...see int(3f) 

realloc(3c).*.see malloc(3c) 

realloc(3x)...see malloc(3x) 

regcmp(3x).compile and execute regular expression 

regex(3x).see regcmp(3x) 

rewind(3s)...see fseek(3s) 

rshift(3f)..see and(3f) 

scanf(3s)...convert formatted input 
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seed48(3c).*.see drand48(3c) 

setbuf(3s).... assign buffering to a stream 

8etgrent(3c)...see getgrent(3c) 

setjmp(3c).non-local goto 

setkey(3c).see crypt(3c) 

setpwent(3c) ..... . ..see getpwent(3c) 

setutent(3c)...see getutent(3c) 

setvbuf(3s).see setbuf(3s) 

sgetl(3x). see sputl(3x) 

sign(3f).Fortran transfer-of-sign intrinsic function 

signal(3f) . ..specify Fortran action on receipt of a system signal 

sin(3f).Fortran sine intrinsic function 

sin(3m).trigonometric functions 

sinh(3f).Fortran hyperbolic sine intrinsic function 

sinh(3m) .. hyperbolic functions 

sleep(3c).suspend execution for interval 

sngl(3f)...see int(3f) 

sprintf(3s).. . see printf(3s) 

sputl(3x).access long integer data in a machine-independent fashion. 

sqrt(3f) ..Fortran square root intrinsic function 

sqrt(3m).see exp(3m) 

srand(3c).see rand(3c) 

srand(3f).see irand(3f) 

srand48(3c) .see drand48(3c) 

sscanf(3s)..see scanf(3s) 

ssignal(3c).software signals 

stdio(3s).standard buffered input/output package 

strcat(3c).string operations 

strchr(3c).see strcat(3c) 

strcmp(3c) .see strcat(3c) 

strcpy(3c).see strcat(3c) 

strcspn(3c).see strcat(3c) 

strlen(3c).see strcat(3c) 

strncat(3c).see strcat(3c) 

strncmp(3c).see strcat(3c) 

stmcpy(3c).see strcat(3c) 

strpbrk(3c). see strcat(3c) 

strrchr(3c) .see strcat(3c) 

strspn(3c).see strcat(3c) 

strtod(3c).... . convert string to double-precision number 

strtok(3c) . .. . see strcat(3c) 

strtol(3c).convert string to integer 

swab(3c)... • • • • swap bytes 

system(3f).issue a shell command from Fortran 

system(3s).. • • • • issue a shell command 

sys.errlist(3c). see perror(3c) 

sys_nerr(3c). see perror(3c) 

tan(3f).Fortran tangent intrinsic function 

tan(3m). . see sin(3m) 

tanh(3f).Fortran hyperbolic tangent intrinsic function 

tanh(3m).see sinh(3m) 

tdelete(3c).....see tsearch(3c) 

tempnam(3s) .see tmpnam(3s) 
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tfind(3c). see tsearch(3c) 

tmpfile(3s)...create a temporary file 

tmpnam(3s).. . . ... . . . . create a name for a temporary file 

toascii(3c). see toupper(3c) 

tolower(3c).. . ..see toupper(3c) 

toupper(3c).translate characters 

tsearch(3c)...manage binary search trees 

ttyname(3c) «... .find name of a terminal 

ttyslot(3c).... . • find the slot in the utmp file of the current user 

twalk(3c).... ..see tsearch(3c) 

tzset(3c).see ctime(3c) 

ungetc(3s)...push character back into input stream 

utmpname(3c)...- • . . . see getutent(3c) 

vfprintf(3s) . . ....see vprintf(3s) 

vfprintf(3x).see vprintf(3x) 

vprintf(3s).print formatted output of a varargs argument list 

vprintf(3x).. print formatted output of a varargs argument list 

vsprintf(3s).see vprintf(3s) 

vsprintf(3x).. ..- .... see vprintf(3x) 

xor(3f)...see and(3f) 

y0(3m).see j0(3m) 
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zabs(3f). see abs(3f) 
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13tol, ltol3 convert between 3-byte integers and long integers .13tol(3c) 

integer and base-64 ASCII string a641,164a convert between long.a64l(3c) 

abort generate an IOT fault.abortf3c) 

abort terminate Fortran program • . . . abort(3f) 

value abs return integer absolute .abs(3c) 

Fortran absolute value abs, iabs, dabs, cabs, sabs .abs(3f) 

abs return integer absolute value .ab$(3c) 

iabs, dabs, cabs, sabs Fortran absolute value abs,.abs(3f) 

fabs floor, ceiling, remainder, absolute value functions /fmod,.floor(3m) 

of a file access determine accessibility.access(2) 

utime set file access and modification times.utime(2) 

machine-independent/ sputl, sgetl access long integer data in a.sputl(3x) 

ldfcn common object file access routines .ldfcn(4) 

/setutent, endutent, utmpname access utmp file entry.getutent(3c) 

access determine accessibility of a file.access(2) 

acct enable or disable process accounting.acct(2) 

mclock return Fortran time accounting.mclock(3f) 

acct per-process accounting file format.acct(4l 

accounting acct enable or disable process.acct(2) 

file format acct per-process accounting.acct(4) 

functions sin, cos, tan, asin, acos, atan, atan2 trigonometric .sin(3m) 

intrinsic function acos, dacos Fortran arccosine *.acos(3f) 

signal signal specify Fortran action on receipt of a system.signal(3f) 

putenv change or add value to environment .putenv(3c) 

part of complex argument aimag, dimag Fortran imaginary.aimag(3f) 

intrinsic function aint, dint Fortran integer part.aint(3f) 

alarm set a process alarm clock.alarm(2) 

alarm set a process alarm clock.alarm(2) 

sbrk change data segment space allocation brk, .brk(2) 

realloc, calloc main memory allocator malloc, free, ..malloc(3c) 

mallinfo fast main memory allocator /calloc, mallopt,.malloc(3x) 

natural logarithm intrinsic/ log, alog, dlog, clog Fortran . ..log(3f) 

logarithm intrinsic/ loglO, aloglO, dloglO Fortran common.Iogl0(3f) 

Fortran/ max, maxO, amaxO, maxi, amaxl, dmaxl.max(3f) 

max, maxO, amaxO, maxi, amaxl, dmaxl Fortran/ .max(3f) 

Fortran/ min, minO, aminO, mini, aminl, dminl.min(3f) 

min, minO, aminO, mini, aminl, dminl Fortran/.min(3f) 

intrinsic functions mod, amod, dmod Fortran remaindering . . . . mod(3f) 

Fortran Bitwise Boolean/ and, or, xor, not, Ishift, rshift.and(3f) 

Fortran nearest integer/ anint, dnint, nint, idnint.. anint(3f) 

editor output a.out common assembler and link . . . . a.out(4) 

ar common archive file format .ar(4) 

acos, dacos Fortran arccosine intrinsic function.acos(3f) 

cpio format of cpio archive.cpio(4) 

archive header of a member of an archive file Idahread read the.ldahread(3x) 

ar common archive file format.. . . ar(4) 

archive file Idahread read the archive header of a member of an.ldahread(3x) 

asin, dasin Fortran arcsine intrinsic function.asin(3f) 

atan2, datan2 Fortran arctangent intrinsic function.atan2(3f) 

atan, datan Fortran arctangent intrinsic function.. . atan(3f) 

Fortran imaginary part of complex argument aimag, dimag *.aimag(3f) 

return Fortran command-line argument getarg .. getarg(3f) 

varargs handle variable argument list.varargs(5) 

formatted output of a varargs argument list /vsprintf print .vprintf(3s) 

formatted output of a varargs argument list /vsprintf print .vprintf(3x) 

getopt get option letter from argument vector .getopt(3c) 

return the number of command line arguments iargc .iargc(3f) 
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set ascii map of ASCII character .. ascii(5) 

ascii map of ASCII character set.ascii(S) 

between long integer and base-64 ASCII string /164a convert.a64l(3c) 

time/ ctime, localtime, gmtime, asctime, tzset convert date and.ctime(3c) 

trigonometric/ sin, cos, tan, asin, acos, atan, atan2.. . sin(3m) 

intrinsic function asin, dasin Fortran arcsine ..asin(3f) 

/a.out common assembler and link editor output .a.out(4) 

assert verify program assertion .assert(3x) 

assert verify program assertion.assert(3x) 

setbuf, setvbuf assign buffering to a stream .setbuf(3s) 

sin, cos, tan, asin, acos, atan, atan2 trigonometric/.sin(3m) 

intrinsic function atan, datan Fortran arctangent.atan(3f) 

sin, cos, tan, asin, acos, atan, atan2 trigonometric functions.sin(3m) 

arctangent intrinsic function atan2, datan2 Fortran.. atan2(3f) 

double-precision number strtod, atof convert string to . ..strtod(3c) 

strtol, atol, atoi convert string to integer .strtol(3c) 

integer strtol, atol, atoi convert string to .strtol(3c) 

terminal capability data base termcap , . ..termcap(4) 

terminal capability data base terminfo . ..terminfo(4) 

convert between long integer and base-64 ASCII string /164a .a64l(3c) 

jO, jl, jn, yO, yl, yn Bessel functions.. . j0(3m) 

fread, fwrite binary input/output.fread(3s) 

bsearch binary search a sorted table .bsearch(3c) 

tfind, tdelete, twalk manage binary search trees tsearch, .. tsearch(3c) 

btest, ibset, ibclr, mvbits bit /ieor, ishft, ishftc, ibits,.ior(3f) 

set/clear hardware OVRIDE bit ovride . ..ovride(2) 

not, lshift, rshift Fortran Bitwise Boolean functions /xor,.and(3fl 

lshift, rshift Fortran Bitwise Boolean functions /or, xor, not,.and(3f) 

space allocation brk, sbrk change data segment .brk(2) 

table bsearch binary search a sorted.bsearch(3c) 

/not, ieor, ishft, ishftc, ibits, btest, ibset, ibclr, mvbits bit.. ior(3f) 

stdio standard buffered input/output package .stdio(3s) 

setbuf, setvbuf assign buffering to a stream .setbuf(3s) 

swab swap bytes ...swab(3c) 

value abs, iabs, dabs, cabs, zabs Fortran absolute.abs(3f) 

data returned by stat system call stat ...stat(5) 

malloc, free, realloc, calloc main memory allocator.malloc(3c) 

main/ malloc, free, realloc, calloc, mallopt, mallinfo fast .malloc(3x) 

intro introduction to system calk and error numbers .intro(2) 

termcap terminal capability data base . ..termcap(4) 

terminfo terminal capability data base.terminfo(4) 

function cos, dcos, ccos Fortran cosine intrinsic.cos(3f) 

ceiling, remainder,/ floor, ceil, fmod, fabs floor,.floor(3m) 

floor, ceil, fmod, fabs floor, ceiling, remainder, absolute/.floor(3m) 

intrinsic function exp, dexp, cexp Fortran exponential.exp(3f) 

allocation brk, sbrk change data segment space.brk(2) 

chmod change mode of file .chmod(2) 

environment putenv change or add value to.putenv(3c) 

chown change owner and group of a file .chown(2) 

nice change priority of a process.nice(2) 

chroot change root directory .chroot(2) 

chdir change working directory.chdir(2) 

pipe create an interprocess channel .pipe(2) 

/sngl, dble, cmplx, dcmplx, ichar, char explicit Fortran type/.int(3f) 

ungetc push character back into input stream.ungetc(3s) 

cuserid get character login name of the user .cuserid(3s) 

getc, getchar, fgetc, getw get character or word from a stream .getc(3s) 

putc, putchar, fputc, putw put character or word on a stream .putc(3s) 

ascii map of ASCII character set.ascii(5) 

iscntrl, isascii classify characters /isprint, isgraph, .isalpha(3c) 
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_tolower, to&scii translate characters /tolower, _toupper,.toupper(3c) 

chdir change working directory .chdir(2) 

processed by fsck checklist list of file systems.checklist(4) 

times get process and child process times.times(2) 

terminate wait wait for child process to stop or.wait(2) 

chmod change mode of file .chmod(2) 

a file chown change owner and group of . . • . chown(2) 

chroot change root directory .chroot(2) 

isgraph, iscntrl, isascii classify characters /isprint,.isalpha(3c) 

inquiries ferror, feof, clearerr, fileno stream status .ferror(3s) 

alarm set a process alarm clock.alarm(2) 

clock report CPU time used.clock(3c) 

intrinsic/ log, alog, dlog, clog Fortran natural logarithm .log(3f) 

close close a file descriptor .close(2) 

Id close, ldaclose close a common object file .ldclose(3x) 

close close a file descriptor .close(2) 

fclose, fflush close or flush a stream.fclose(3s) 

/telldir, seekdir, rewinddir, closedir directory operations.directory:(3x) 

idint, real, float, sngl, dble, cmplx, dcmplx, ichar, char/ /ifix,.int(3f) 

system issue a shell command.system(3s) 

system issue a shell command from Fortran .system(3f) 

iargc return the number of command line arguments.iargc(3f) 

getarg return Fortran command-line argument.getarg(3f) 

ar common archive file format.ar(4) 

output /a.out common assembler and link editor.a.out(4) 

loglO, aloglO, dloglO Fortran common logarithm intrinsic/.. . Iogl0(3f) 

ldclose, ldaclose close a common object file .ldclose(3x) 

read the file header of a common object file ldfhread ....... ldfhread(3x) 

number entries of a section of a common object file /seek to line.ldlseek(3x) 

to the optional file header of a common object file /seek.ldohseek(3x) 

entries of a section of a common object file /to relocation.ldrseek(3x) 

indexed named section header of a common object file /read an .ldshread(3x) 

to an indexed named section of a common object file /seek.ldsseek(3x) 

of a symbol table entry of a common object file /the index .ldtbindex(3x) 

indexed symbol table entry of a common object file /read an.ldtbread(3x) 

seek to the symbol table of a common object file ldtbseek .ldtbseek(3x) 

line number entries in a common object file linenum .linenum(4) 

relocation information for a common object file reloc .reloc(4) 

scnhdr section header for a common object file .scnhdr(4) 

routines Idfcn common object file? access .ldfcn(4) 

ldopen, Idaopen open a common object file for reading .ldopen(3x) 

/line number entries of a common object file function.ldlread(3x) 

entry /retrieve symbol name for common object file symbol table.ldgetname(3x) 

format syms common object file symbol table.syms(4) 

filehdr file header for common object files.filehdr(4) 

ftok standard interprocess communication package.ftok(3c) 

Ige, Igt, He, lit string comparison intrinsic functions.lge(3f) 

expression regcmp, regex compile and execute regular .regcmp(3x) 

regexp regular expression compile and match routines .regexp(5) 

term format of compiled term file...term(4) 

erf, erfc error function and complementary error function.erf(3m) 

dimag Fortran imaginary part of complex argument aimag, .aimag(3f) 

function conjg, dconjg Fortran complex conjugate intrinsic.conjg(3f) 

table entry of a/ ldtbindex compute the index of a symbol .ldtbindex(3x) 

uxrc ICON/UXB run-time configuration file .uxrc(4) 

conjugate intrinsic function conjg, dconjg Fortran complex.conjg(3f) 

conjg, dconjg Fortran complex conjugate intrinsic function.conjg(3f) 

an out-going terminal line connection dial establish ........ dial(3c) 

math math functions and constants.math(5) 

fcntl file control.fcntl(2) 
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ioctl 

msgctl message 
semctl semaphore 
shmctl shared memory 
fcntl file 
term 

char explicit Fortran type 
and long integers 13tol, ltol3 
base-64 ASCII string a641, 164a 
/localtime, gmtime, asetime, tzset 
string ecvt, fevt, gevt 
scanf, fscanf, sscanf 
double-precision/ strtod, atof 
strtol, atol, atoi 
file 

intrinsic function 
trigonometric functions sin, 
cosine intrinsic function 
sinh, 

cos, dcos, ccos Fortran 
cosh, dcosh Fortran hyperbolic 

cpio format of 
clock report 
rewrite an existing one 
file tmpnam, tempnam 
existing one creat 
fork 
tmpfile 
pipe 

umask set and get file 
optimization package curses 
DES encryption 
function sin, dsin, 
intrinsic function sqrt, dsqrt, 
terminal 

asetime, tzset convert date/ 
uname get name of 
the slot in the utmp file of the 
getewd get path-name of 
optimization package 
name of the user 
absolute value abs, iabs, 
intrinsic function acos, 
function asin, 
termcap terminal capability 
terminfo terminal capability 
/sgetl access long integer 
plock lock process, text, or 

stat 

brk,sbrk change 
types primitive system 
intrinsic function atan, 
intrinsic function atan2, 
/gmtime, asetime, tzset convert 
/ifix, idint, real, float, sngl, 
/real, float, sngl, dble, cmplx, 
conjugate intrinsic/ conjg, 
intrinsic function cos, 
intrinsic function cosh, 


control device. 

control operations. 

control operations .. 

control operations. 

control options. 

conventional names for terminals 
conversion /cmplx, dcmplx, ichar, 
convert between 3-byte integers 
convert between long integer and 
convert date and time to string 
convert floating-point number to 
convert formatted input . . . 
convert string to ...... 

convert string to integer . . . 
core format of memory image 
cos, dcos, ccos Fortran cosine 
cos, tan, asin, acos, atan, atan2 
cosh, dcosh Fortran hyperbolic 
cosh, tanh hyperbolic functions 
cosine intrinsic function . . . 

cosine intrinsic function . . . 

cpio format of cpio archive 
cpio archive ........ 

CPU time used.. . 

creat create a new file or . . 
create a name for a temporary 
create a new file or rewrite an 

create a new process. 

create a temporary file . • . . 
create an interprocess channel 

creation mask. 

CRT screen handling and . . 
crypt, setkey, encrypt generate 
csin Fortran sine intrinsic . . 
csqrt Fortran square root . . 
ctermid generate file name for 
ctime, localtime, gmtime, . • . 
current UNIX system .... 
current user ttyslot find . . 
current working directory . . 
curses CRT screen handling anc 
cuserid get character login 
dabs, cabs, zabs Fortran . . 
dacos Fortran arccosine . . . 
dasin Fortran arcsine intrinsic 

data base . 

data base . 

data in a machine-independent/ 

data in memory. 

data returned by stat system call 
data segment space allocation 

data types. 

datan Fortran arctangent • • 
datan2 Fortran arctangent 
date and time to string • . • 
dble, cmplx, dcmplx, ichar, char/ 
dcmplx, ichar, char explicit/ . 
dconjg Fortran complex . . . 
dcos, ccos Fortran cosine . . 
dcosh Fortran hyperbolic cosine 


ioctl(2) 

msgctl(2) 

semctl(2) 

shmctl(2) 

fcntl(5) 

term(5) 

int(3f) 

13tol(3c) 

&64l(3c) 

ctime(3c) 

ecvt(3c) 

scanf(3s) 

strtod(3c) 

strtol(3c) 

core(4) 

cos(3f) 

sin(3m) 

cosh(3f) 

sinh(3m) 

cos(3f) 

cosh(3f) 

cpiof4) 

cpio(4) 

clock(3c) 

creat(2) 

tmpnam(3s) 

creat(2) 

fork(2) 

tmpfile(3s) 

pipe(2) 

umask(2) 

curses(3x) 

crypt(3c) 

sin(3f) 

sqrt(3f) 

ctermid(3s) 

ctime(3c) 

unamef2) 

ttyslot(3c) 

getcwd(3c) 

. curses(3x) 

. cuserid(3s) 

» abs(3f) 
acos(3f) 

. asin(3f) 

, termcap(4) 

. terminfo(4) 

► sputl(3x) 

► plock(2) 

► stat(5) 

► brk(2) 

* types(5) 

» atan(3f) 

, atan2(3fl 
» ctime(3c) 

. int(3f) 

. int(3f) 

. conjg(3f) 

. cos(3f) 

• cosh(3f) 
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intrinsic functions dim, 
crypt, setkey, encrypt generate 
close close a file 
dup duplicate an open file 
from SLPT printers dosprinters 

access 
ioctl control 
intrinsic function exp, 
terminal line connection 
dim, ddim, idim positive 
difference intrinsic functions 
complex argument aimag, 
intrinsic function aint, 

dir format of 
cbdir change working 
chroot change root 
get path-name of current working 
unlink remove 
telldir, seekdir, rewinddir,/ 
seekdir, rewinddir, closedir 
ordinary file mknod make a 
acct enable or 
list of MPS/DOS virtual 
list of SMILE virtual 
hypot Euclidean 
/lcong48 generate uniformly 
logarithm intrinsic/ log, alog, 
intrinsic/ loglO, aloglO, 
max, maxO, amaxO, maxi, amaxl, 
min, minO, aminO, mini, aminl, 
intrinsic functions mod, amod, 
nearest integer functions anint, 
virtual disks 
spooled output from SLPT/ 
intrinsic function dprod 
strtod, atof convert string to 
intrinsic function 
nrand48, mrand48, jrand48,/ 
intrinsic function sign, isign, 
intrinsic function sin, 
intrinsic function sinh, 
root intrinsic function sqrt, 
function tan, 
tangent intrinsic function tanh, 
descriptor 
dup 

floating-point number to string 
end, etext, 

/a .out common assembler and link 
effective user, real group, and 
/getgid, getegid get real user, 
accounting acct 
crypt, setkey, 
setkey, encrypt generate DES 
locations in program 
/getgrgid, getgrnam, setgrent, 
/getpwuid, getpwnam, setpwent, 
/getutline, pututline, setutent, 
nlist get 


ddim, idim positive difference .dim(3f) 

DES encryption.crypt(3c) 

descriptor .close(2) 

descriptor .dup(2) 

destinations for spooled output.dosprinters(4) 

determine accessibility of a file.access(2) 

device.ioctl(2) 

dexp, cexp Fortran exponential .exp(3f) 

dial establish an out-going .dial(3c) 

difference intrinsic functions .dim(3fl 

dim, ddim, idim positive .dim(3f) 

dimag Fortran imaginary part of . . . . aimag(3f) 

dint Fortran integer part.aint(3f) 

dir format of directories .dir(4l 

directories • • • ..dir(4) 

directory.chdir(2) 

directory.chroot(2) 

directory getewd .getcwd(3c) 

directory entry.unlink(2) 

directory: opendir, readdir,.directory:(3x) 

directory operations /telldir,.directory:(3x) 

directory, or a special or.• mknod(2) 

disable process accounting . ..acct(2) 

disks dosdisks .dosdisks(4) 

disks smiledisks .smiledisks(4) 

distance function .hypot(3m) 

distributed pseudo-random numbers .... drand48(3c) 

dlog, clog Fortran natural.log(3H 

dloglO Fortran common logarithm .... Iogl0(3f) 

dmaxl Fortran maximum-value/.max(3f) 

dminl Fortran minimum-value/.min(3f) 

dmod Fortran remaindering.mod(3f) 

dnint, nint, idnint Fortran .anint(3f) 

dosdisks list of MPS/DOS.dosdisks(4) 

dosprinters destinations for ....... dosprinters(4) 

double precision product.dprod(3f) 

double-precision number.strtod(3c) 

dprod double precision product .dprod(3f) 

drand48, erand48, lrand48,.drand48(3c) 

dsign Fortran transfer-of-sign.sign(3f) 

dsin, csin Fortran sine .sin(3f) 

dsinh Fortran hyperbolic sine .sinh(3f) 

dsqrt, csqrt Fortran square .sqrt(3f) 

dtan Fortran tangent intrinsic.tan(3f) 

dtanh Fortran hyperbolic.tanh(3f) 

dup duplicate an open file.dup(2l 

duplicate an open file descriptor.dup(2) 

ecvt, fevt, gevt convert.ecvt(3c) 

edata last locations in program .end(3c) 

editor output.. . a.out(4) 

effective group IDs /real user,.getuid(2) 

effective user, real group, and/ .. getuid(2) 

enable or disable process.acct(2) 

encrypt generate DES encryption .... crypt(3cl 

encryption crypt,.crypt(3c) 

end, etext, edata last.end(3c) 

endgrent, fgetgrent get group/.getgrent(3c) 

endpwent, fgetpwent get/. getpwent(3c) 

endutent, utmpname access utmp/ .... getutent(3c) 
entries from name list.nlist(3c) 
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linenum line number entries in a common object file .linenum(4) 

/ldlitem manipulate line number entries of a common object file/.ldlread(3x) 

/Idnlseek seek to line number entries of a section of a common/.ldlseek(3x) 

/ldnrseek seek to relocation entries of a section of a common/.ldrseek(3x) 

fgetgrent get group file entry /setgrent, endgrent, .getgrent(3c) 

fgetpwent get password file entry /setpwent, endpwent, . ,.getpwent(3c) 

utmpname access utmp file entry /setutent, endutent,.getutent(3c) 

common object file symbol table entry /retrieve symbol name for .ldgetname(3x) 

putpwent write password file entry ...putpwent(3c) 

unlink remove directory entry .unlink(2) 

utmp, wtmp utmp and wtmp entry formats . . . ..utmp(4) 

/the index of a symbol table entry of a common object file.ldtbindex(3x) 

/read an indexed symbol table entry of a common object file.ldtbread(3x) 

environ user environment.environ(5) 

environ user environment .environ(5) 

putenv change or add value to environment .putenv(3c) 

profile setting up an environment at login time .profile(4) 

getenv return value for environment name.getenv(3c) 

getenv return Fortran environment variable . . • . ..getenv(3f) 

mrand48, jrand48,/ drand48, erand48, lrand48, nrand48,.drand48(3c) 

complementary error function erf, erfc error function and .erf(3ml 

complementary error/ erf, erfc error function and.. • • . erf(3m) 

system error messages perror, ermo, sys_errlist, sys^nerr .perror(3c) 

error function and complementary error function erf, erfc .erf(3m| 

error function erf, erfc error function and complementary.erf(3m) 

sys^erriist, sys^nerr system error messages perror, errno,.perror(3c) 

introduction to system calls and error numbers intro .intro(2) 

matherr error-handling function .matherr(3m) 

line connection dial establish an out-going terminal.dial(3c) 

program end, etext, edata last locations in .end(3c) 

hypot Euclidean distance function.hypot(3m) 

execlp, execvp execute a file execl, execv, execle, execve,.execl(2) 

execute a file execl, execv, execle, execve, execlp, execvp.execl(2) 

execl, execv, execle, execve, execlp, execvp execute a file.execl(2) 

execle, execve, execlp, execvp execute a file execl, execv,.execl(2) 

regcmp, regex compile and execute regular expression .regcmp(3x) 

sleep suspend execution for interval .sleep(3c) 

monitor prepare execution profile.monitor(3c) 

profil execution time profile .profil(2) 

execvp execute a file execl, execv, execle, execve, execlp, .execl(2) 

a file execl, execv, execle, execve, execlp, execvp execute.execl(2) 

execv, execle, execve, execlp, execvp execute a file execl, .execl(2) 

create a new file or rewrite an existing one creat .. . . . . creat(2) 

exit, _exit terminate process.exit(2) 

exit, _exit terminate process .•••••. cxit(2) 

exponential intrinsic function exp, dexp, cexp Fortran.exp(3f) 

exponential, logarithm, power,/ exp, log, loglO, pow, sqrt.exp(3m) 

/dble, cmplx, dcmplx, ichar, char explicit Fortran type conversion.int(3f) 

exp, dexp, cexp Fortran exponential intrinsic function.exp(3f) 

exp, log, loglO, pow, sqrt exponential, logarithm, power,/.exp(3m) 

compile and execute regular expression regcmp, regex .regcmp(3x) 

routines regexp regular expression compile and match ....... regexp(5) 

absolute/ floor, ceil, fmod, fabs floor, ceiling, remainder, .floor(3m) 

data in a machine-independent fashion, /access long integer.sputl(3x) 

/calloc, mallopt, mallinfo fast main memory allocator .malloc(3x) 

abort generate an IOT fault.abort(3c) 

stream fclose, ffiush close or flush a.fclose(3s) 

fcntl file control ..fcntl(2| 

fcntl file control options.fcntl(5) 

floating-point number to/ ecvt, fcvt, gcvt convert .ecvt(3c) 
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fopen, freopen, fdopen open a stream • ..fopen(3s) 

status inquiries Terror, feof, clearerr, fileno stream .ferror(3s| 

stream status inquiries Terror, TeoT, clearerr, fileno.■ . . ferror(3s) 

Tclose, flush close or flush a stream.fclose(3s) 

word Trom a/ getc, getchar, fgetc, getw get character or.getc(3s) 

/getgrnam, setgrent, endgrent, Tgetgrent get group file entry .getgrent(3c) 

/getpwnam, setpwent, endpwent, Tgetpwent get password file/.getpwent(3c) 

stream gets, Tgets get a string Trom a .gets(3s) 

determine accessibility oT a file access • •.access(2) 

chmod change mode of file .chmod(2) 

change owner and group of a file chown .chown(2) 

core format of memory image file .core(4) 

execlp, execvp execute a file /execv, execle, execve, ........ execl(2) 

group group file .group(4) 

issue issue identification file .issue(4) 

header of a member of an archive file Idahread read the archive.ldahread(3x) 

ldaclose close a common object file ldclose,.ldclose(3x) 

file header of a common object file ldfhread read the.ldfhread(3x) 

of a section of a common object file /seek to line number entries.ldlseek(3x) 

file header of a common object file /seek to the optional . ..ldohseek(3x) 

of a section of a common object file /seek to relocation entries .ldrseek(3x) 

section header of a common object file /read an indexed named .ldshread(3x) 

named section of a common object file /seek to an indexed .ldsseek(3x) 

table entry of a common object file /the index of a symbol.ldtbindex(3x) 

table entry of a common object file /read an indexed symbol . *.ldtbread(3x) 

symbol table of a common object file ldtbseek seek to the.ldtbseek(3x) 

number entries in a common object file linenum line ..linenum(4) 

link link to a file .link(2) 

or a special or ordinary file mknod make a directory, .mknod(2) 

passwd password file .passwd(4) 

read read from file .read(2) 

information for a common object file reloc relocation .reloc(4) 

sccsfile format of SCCS file .. sccsfile(4) 

header for a common object file scnhdr section.scnhdr(4) 

swrite synchronous write on a file .swrite(2) 

term format of compiled term file. .. term(4) 

tmpfile create a temporary file .tmpfile(3s) 

create a name for a temporary file tmpnam, tempnam .tmpnam(3s) 

ICON/UXB run-time configuration file uxrc .uxrc(4) 

write write on a file .write(2) 

times utime set file access and modification.utime(2) 

ldfcn common object file access routines.ldfcn(4) 

fcntl file control.fcntl(2) 

fcntl file control options.fcntl(5) 

umask set and get file creation mask.umask(2) 

close close a file descriptor.close(2) 

dup duplicate an open file descriptor.dup(2) 

endgrent, fgetgrent get group file entry /getgrnam, setgrent, ...... getgrent(3c) 

fgetpwent get password file entry /setpwent, endpwent,.getpwent(3c) 

endutent, utmpname access utmp file entry /pututline, setutent, .getutent(3c) 

putpwent write password file entry. putpwent(3c) 

ldaopen open a common object file for reading ldopen,.ldopen(3x) 

acct per-process accounting file format .acct(4) 

ar common archive file format .ar(4) 

intro introduction to file formats.intro{4) 

number entries of a common object file function /manipulate line.ldlread(3x) 

files filehdr file header for common object.filehdr(4) 

file ldfhread read the file header of a common object .ldfhread(3x) 

ldohseek seek to the optional file header of a common object/ ...... ldohseek(3x) 

mktemp make a unique file name . ..mktemp(3c) 
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ctermid generate file name for terminal .ctermid(3s) 

/find the slot in the utmp file of the current user.ttyslot(3c) 

creat create a new file or rewrite an existing one.creat(2) 

lseek move read/write file pointer.lseek(2) 

rewind, ftell reposition a file pointer in a stream fseek,.fseek(3s) 

stat, fstat get file status .stat(2) 

symbol name for common object file symbol table entry /retrieve .ldgetname(3x) 

syms common object file symbol table format . • ..syms(4) 

mount mount a file system .mount(2) 

umount unmount a file system .. • . . umount(2) 

ust&t get file system statistics...ustat(2) 

mnttab mounted file system table ....mnttab(4) 

fs format of file system volume fs(4) 

checklist list of file systems processed by fsck.. . checklist(4) 

ftw walk a file tree . . . ..ftw(3c) 

object files filehdr file header for common.filehdr(4) 

Terror, feof, clearerr, fileno stream status inquiries .ferror(3s) 

file header for common object files filehdr .filehdr(4) 

format specification in text files fspec * . *.fspec(4) 

string, format of graphical files gps graphical primitive.gps(4) 

lockf record locking on files.lockf(3c) 

ttyname, isatty find name of a terminal .ttyname(3c) 

the current user ttyslot find the slot in the utmp file of.ttyslot(3c) 

ichar,/ int, ifix, idint, real, float, sngl, dble, cmplx, dcmplx,.int(3f) 

ecvt, fcvt, gcvt convert floating-point number to string.. ecvt(3c) 

ldexp, modf manipulate parts of floating-point numbers frexp,.frexp(3c) 

ceiling, remainder, absolute/ floor, ceil, fmod, fabs floor, .floor(3m) 

absolute/ floor, ceil, fmod, fabs floor, ceiling, remainder,.floor(3m) 

fclose, ffiush close or flush a stream ..fclose(3s) 

remainder, absolute/ floor, ceil, fmod, fabs floor, ceiling,.floor(3m) 

stream fopen, freopen, fdopen open a.fopen(3s) 

fork create a new process.fork(2) 

per-process accounting file format acct .acct(4) 

ar common archive file format.ar(4) 

common object file symbol table format syms .syms(4) 

inode format of an i-node .inode(4) 

term format of compiled term file.term(4) 

cpio format of cpio archive.cpio(4) 

dir format of directories.. dir(4) 

fs format of file system volume .fs(4) 

gps graphical primitive string, format of graphical files.gps(4) 

core format of memory image file .core(4) 

sccsfile format of SCCS file .sccsfile(4) 

files fspec format specification in text ..fspec(4) 

intro introduction to file formats ..intro(4) 

utmp, wtmp utmp and wtmp entry formats ..utmp(4) 

scanf, fscanf, sscanf convert formatted input.scanf(3s) 

printf, fprintf, sprintf print formatted output.printf(3s) 

/vfprintf, vsprintf print formatted output of a varargs/.vprintf(3s) 

/vfprintf, vsprintf print formatted output of a varargs/.vprintf(3x) 

issue a shell command from Fortran system .system(3f) 

abs, iabs, dabs, cabs, sabs Fortran absolute value.abs(3f) 

system signal signal specify Fortran action on receipt of a .signal(3f) 

function acos, dacos Fortran arccosine intrinsic.acos(3f) 

function asin, dasin Fortran arcsine intrinsic ..asin(3f) 

function atan2, datan2 Fortran arctangent intrinsic .atan2(3f) 

function atan, datan Fortran arctangent intrinsic ....... atan(3f) 

and, or, xor, not, lshift, rshift Fortran Bitwise Boolean functions.and(3f) 

getarg return Fortran command-line argument .getarg(3f) 

intrinsic/ loglO, aloglO, dloglO Fortran common logarithm.Iogl0(3f) 


xxiv 


Icon International, Inc. 































































Permuted Index 


intrinsic function conjg, dconjg Fortran complex conjugate.conjg(3f) 

cos, dcos, ccos Fortran cosine intrinsic function .cos(3f) 

getenv return Fortran environment variable.getenv(3f) 

function exp, dexp, cexp Fortran exponential intrinsic.exp(3f) 

intrinsic function cosh, dcosh Fortran hyperbolic cosine .cosh(3f) 

function sinh, dsinh Fortran hyperbolic sine intrinsic.sinh(3f) 

intrinsic function tanh, dtanh Fortran hyperbolic tangent.tanh(3f) 

argument aimag, dimag Fortran imaginary part of complex . . . • aimag(3f) 

function aint, dint Fortran integer part intrinsic.aint(3f) 

/maxO, amaxO, maxi, amaxl, dmaxl Fortran maximum-value functions . . . . . max(3f) 

/minO, aminO, mini, aminl, dminl Fortran minimum-value functions . . . . . min(3f) 

intrinsic/ log, alog, dlog, clog Fortran natural logarithm.log(3f) 

anint, dnint, nint, idnint Fortran nearest integer functions.anint(3f) 

abort terminate Fortran program .abort(3f) 

functions mod, amod, dmod Fortran remaindering intrinsic .mod(3f) 

sin, dsin, csin Fortran sine intrinsic function .sin(3f) 

function sqrt, dsqrt, csqrt Fortran square root intrinsic ....... sqrt(3f) 

len return length of Fortran string .len(3f) 

index return location of Fortran substring.index(3f) 

function tan, dtan Fortran tangent intrinsic.tan(3f) 

mclock return Fortran time accounting.mclock(3f) 

intrinsic/ sign, isign, dsign Fortran transfer-of-sign .sign(3f) 

dcmplx, ichar, char explicit Fortran type conversion /cmplx, ..... int(3f) 

formatted output printf, fprintf, sprintf print .printf(3s) 

word on a stream putc, putchar, fputc, putw put character or .putc(3s) 

puts, fputs put a string on a stream.puts(3s) 

input/output fread, fwrite binary .fread(3s) 

memory allocator malloc, free, realloc, calloc main .malloc(3c) 

mallinfo fast main/ malloc, free, realloc, calloc, mallopt, .malloc(3x) 

fopen, freopen, fdopen open a stream.fopen(3s) 

parts of floating-point numbers frexp, ldexp, modf manipulate.frexp(3c) 

fs format of file system volume.fs(4) 

formatted input scanf, fscanf, sscanf convert.scanf(3s) 

list of file systems processed by fsck checklist ..checklist(4) 

a file pointer in a stream fseek, rewind, ftell reposition .fseek(3s) 

text files fspec format specification in.fspec(4) 

stat, fstat get file status.stat(2) 

in a stream fseek, rewind, ftell reposition a file pointer.fseek(3s) 

communication package ftok standard interprocess .ftok(3c) 

ftw walk a file tree ..ftw(3c) 

Fortran arccosine intrinsic function acos, dacos .acos(3f) 

Fortran integer part intrinsic function aint, dint ••••••••••• aint(3f) 

dasin Fortran arcsine intrinsic function asin,.asin(3f) 

Fortran arctangent intrinsic function atan2, datan2 .. atan2(3f) 

Fortran arctangent intrinsic function atan, datan .. atan(3f) 

complex conjugate intrinsic function conjg, dconjg Fortran .conjg(3f) 

ccos Fortran cosine intrinsic function cos, dcos,.cos(3f) 

hyperbolic cosine intrinsic function cosh, dcosh Fortran .cosh(3f) 

precision product intrinsic function dprod double ......... dprod(3f) 

function and complementary error function erf, erfc error.erf(3m) 

Fortran exponential intrinsic function exp, dexp, cexp .exp(3f) 

gamma log gamma function .gamma(3m) 

hypot Euclidean distance function .hypot(3m) 

entries of a common object file function /manipulate line number.ldlread(3x) 

common logarithm intrinsic function /dloglO Fortran.Iogl0(3f) 

natural logarithm intrinsic function /dlog, clog Fortran.log(3f) 

matherr error-handling function .matherr(3m) 

prof profile within a function. prof(5) 

transfer-of-sign intrinsic function /isign, dsign Fortran.sign(3f) 

csin Fortran sine intrinsic function sin, dsin,.sin(3f) 
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Fortran hyperbolic sine intrinsic function sinh, dsinh .sinh(3f) 

Fortran square root intrinsic function sqrt, dsqrt, csqrt .sqrt(3f) 

dtan Fortran tangent intrinsic function tan,.tan(3f) 

hyperbolic tangent intrinsic function tanh, dtanh Fortran.tanh(3f) 

function erf, erfc error function and complementary error.erf(3m) 

rshift Fortran Bitwise Boolean functions /or, xor, not, lshift,.and(3f) 

idnint Fortran nearest integer functions anint, dnint, nint, .anint(3f) 

positive difference intrinsic functions dim, ddim, idim .dim(3f) 

logarithm, power, square root functions /sqrt exponential,.exp(3m) 

remainder, absolute value functions /fabs floor, ceiling, .floor(3m) 

jO, jl, jn, yO, yl, yn Bessel functions.j0(3m) 

lit string comparison intrinsic functions lge, lgt, lie, . . . . *.lge(3f) 

dmaxl Fortran maximum-value functions /amaxO, maxi, amaxl,.max(3f) 

dminl Fortran minimum-value functions /aminO, mini, aminl,.min(3f) 

Fortran remaindering intrinsic functions mod, amod, dmod .mod(3f) 

acos, atan, atan2 trigonometric functions sin, cos, tan, asin, .sin(3m) 

sinh, cosh, tanh hyperbolic functions.sinh(3m) 

math math functions and constants .math(5) 

fread, fwrite binary input/output .fread(3s) 

gamma log gamma function.gamma(3m) 

gamma log gamma function.gamma(3m) 

number to string ecvt, fcvt, gcvt convert floating-point .ecvt(3c) 

abort generate an IOT fault.abort(3c) 

crypt, setkey, encrypt generate DES encryption.crypt(3c) 

ctermid generate file name for terminal.ctermid(3s) 

/jrand48, srand48, seed48, lcong48 generate uniformly distributed/.drand48(3c) 

rand, srand random number generator irand, .irand(3f) 

srand simple random-number generator rand,.rand(3c) 

command-line argument getarg return Fortran .getarg(3f) 

character or word from a stream getc, getchar, fgetc, getw get .getc(3s) 

character or word from a/ getc, getchar, fgetc, getw get.getc(3s) 

working directory getcwd get path-name of current.getcwd(3c) 

getuid, geteuid, getgid, getegid get real user,/ .getuid(2) 

environment variable getenv return Fortran .getenv(3f) 

environment name getenv return value for.getenv(3c) 

real user, effective/ getuid, geteuid, getgid, getegid get .. . getuid(2j 

effective user,/ getuid, geteuid, getgid, getegid get real user,.getuid(2) 

setgrent, endgrent, fgetgrent/ getgrent, getgrgid, getgrnam,.getgrent(3c) 

endgrent, fgetgrent/ getgrent, getgrgid, getgrnam, setgrent,.getgrent(3c) 

fgetgrent/ getgrent, getgrgid, getgrnam, setgrent, endgrent,.. getgrent(3c) 

getlogin get login name.getlogin(3c) 

argument vector getopt get option letter from .getopt(3c) 

getpass read a password .getpass(3c) 

process group, and/ getpid, getpgrp, getppid get process, .getpid(2l 

process, process group, and/ getpid, getpgrp, getppid get.getpidm 

group, and/ getpid, getpgrp, getppid get process, process.getpid(2) 

getpw get name from UID.getpw(3c) 

setpwent, endpwent, fgetpwent/ getpwent, getpwuid, getpwnam,.getpwent(3cl 

fgetpwent/ getpwent, getpwuid, getpwnam, setpwent, endpwent,.getpwent(3c) 

endpwent, fgetpwent/ getpwent, getpwuid, getpwnam, setpwent,.getpwent(3c) 

stream gets, fgets get a string from a ...... gets(3s) 

and terminal settings used by getty gettydefs speed.gettydefs(4) 

settings used by getty gettydefs speed and terminal .gettydefs(4) 

get real user, effective user,/ getuid, geteuid, getgid, getegid .getuid(2) 

pututline, setutent, endutent,/ getutent, getutid, getutline,.getutent(3c) 

setutent, endutent,/ getutent, getutid, getutline, pututline, .getutent(3c) 

endutent,/ getutent, getutid, getutline, pututline, setutent,.getutent(3c) 

a stream getc, getchar, fgetc, getw get character or word from.getc(3s) 

date and time/ ctime, localtime, gmtime, asctime, tzset convert.ctime(3c) 

setjmp, longjmp non-local goto ..setjmp(3c) 
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format of graphical files 
primitive string, format of 
format of graphical files gps 

plot 

plot 

/real user, effective user, real 
/getppid get process, process 

group 

endgrent, fgetgrent get 
setpgrp set process 
user, real group, and effective 
setuid, setgid set user and 
chown change owner and 
send a signal to a process or a 
ssignal, 
varargs 
curses CRT screen 
ovride set /clear 
hcreate, hdestroy manage 
search tables hsearch, 
tables hsearch, hcreate, 
scnhdr section 
filehdr file 
ldfhread read the file 
/seek to the optional file 
/read an indexed named section 
file ldahread read the archive 
manage hash search tables 
function cosh, dcosh Fortran 
sinh, cosh, tanh 
function sinh, dsinh Fortran 
function tanh, dtanh Fortran 
function 
absolute value abs, 
ibits, btest, ibset, ibclr,/ ior, 
command line arguments 
ishftc, ibits, btest, ibset, 
iand, not, ieor, ishft, ishftc, 
ishft, ishftc, ibits, btest, 
/float, sngl, dble, cmplx, dcmplx, 

file uxrc 

setpgrp set process group 
issue issue 
intrinsic functions dim, ddim, 
cmplx, dcmplx, ichar,/ int, ifix, 
functions anint, dnint, nint, 
process group, and parent process 
real group, and effective group 
setgid set user and group 
btest, ibset,/ ior, iand, not, 
dble, cmplx, dcmplx, ichar,/ int, 
core format of memory 
argument aimag, dimag Fortran 
Fortran substring 
a common/ ldtbindex compute the 
Idshread, ldnshread read an 
ldsseek, Idnsseek seek to an 
common object/ ldtbread read an 
mttys Multi-Link partition 


gps graphical primitive string, . . 
graphical files gps graphical . . . 
graphical primitive string, . . . . 

graphics interface. 

graphics interface subroutines . . . 

group group file . 

group, and effective group IDs . . . 
group, and parent process IDs . . . 

group file. 

group file entry /setgrent, . . . . 

group ID. 

group IDs /real user, effective . . . 

group IDs . 

group of a file. 

group of processes kill . 

gsignal software signals. 

handle variable argument list . . • 
handling and optimization package 

hardware OVRIDE bit. 

hash search tables hsearch, . . . . 
hcreate, hdestroy manage hash 
hdestroy manage hash search . • 
header for a common object file . . 
header for common object files . . 

header of a common object file . . 

header of a common object file . . 

header of a common object file . . 

header of a member of an archive . 
hsearch, hcreate, hdestroy . . . . 
hyperbolic cosine intrinsic .... 

hyperbolic functions. 

hyperbolic sine intrinsic . 

hyperbolic tangent intrinsic .... 
hypot Euclidean distance .... 
iabs, dabs, cabs, zabs Fortran . . 
iand, not, ieor, ishft, ishftc, .... 
iargc return the number of ... 
ibclr, mvbits bit /ieor, ishft, . . . 
ibits, btest, ibset, ibclr,/ ior, . . . 
ibset, ibclr, mvbits bit /ieor, . . 
ichar, char explicit Fortran/ . . 
ICON/UXB run-time configuration 

ID. 

identification file . 

idim positive difference. 

idint, real, float, sngl, dble, » • • • 
idnint Fortran nearest integer . . 
IDs /getppid get process, .... 
IDs /real user, effective user, . . . 

IDs setuid,. 

ieor, ishft, ishftc, ibits,. 

ifix, idint, real, float, sngl, .... 

image file.. 

imaginary part of complex .... 

index return location of. 

index of a symbol table entry of . . 
indexed named section header of a/ 
indexed named section of a common/ 
indexed symbol table entry of a ♦ . 
information. 


gP s (4) 

gps(4) 

gps(4) 

plot(4) 

plot(3x) 

group(4) 

getuid(2l 

getpid(2) 

group(4) 

getgrent(3c) 

setpgrp(2) 

getuid(2) 

setuid(2) 

chown(2) 

kill(2) 

ssignal(3c) 

varargs(5) 

curses(3x) 

ovride(2) 

hsearch(3c) 

hsearch(3c^ 

hsearch(3c) 

scnhdr(4) 

filehdr(4) 

ldfhread(3x) 

ldohseek(3xl 

ldshread(3x) 

ldahread(3x) 

hsearch(3c) 

cosh(3f) 

sinh(3m) 

sinh(3f) 

tanh(3f) 

hypot(3m) 

abs(3f) 

ior(3fl 

iargc(3f) 

ior(3f) 

ior(3f) 

ior(3f) 

int(3f) 

uxrc(4) 

setpgrp(2) 

issue(4) 

dim(3f) 

int(3f) 

anint(3f) 

getpid(2) 

getuid(2) 

setuid(2) 

ior(3f) 

int(3f) 

core(4) 

aimag(3f) 

index(3f) 

ldtbindex(3x) 

ldshread(3x) 

ldsseek(3x) 

ldtbread(3x) 

mttys(4) 
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file reloc relocation information for a common object.reloc(4) 

inittab script for the init process.inittab(4) 

popen, pclose initiate pipe to/from a process .popen(3s) 

process inittab script for the init.inittab(4) 

inode format of an i*node.inode(4) 

inode format of an i-node . ..inode(4) 

sscanf convert formatted input scanf, fscanf, . . ..scanf(3s) 

ungetc push character back into input stream ..ungetc(3s) 

fread, fwrite binary input/output.fread(3s) 

stdio standard buffered input/output package.stdio(3s) 

clearerr, fileno stream status inquiries ferror, feof,.ferror(3s) 

sngl, dble, cmplx, dcmplx,/ int, ifix, idint, real, float,.int(3f) 

atol, atoi convert string to integer strtol,.strtol(3c) 

abs return integer absolute value.abs(3c) 

a64l, 164a convert between long integer and base-64 ASCII string .a64l(3c) 

sputl, sgetl access long integer data in a/.sputl(3x) 

nint, idnint Fortran nearest integer functions anint, dnint, .anint(3f) 

aint, dint Fortran integer part intrinsic function.aint(3f) 

between 3-byte integers and long integers 13tol, ltol3 convert.13tol(3c) 

/ltol3 convert between 3-byte integers and long integers .13tol(3c) 

plot graphics interface...plot(4) 

plot graphics interface subroutines.plot(3x) 

pipe create an interprocess channel...pipe(2) 

package ftok standard interprocess communication.ftok(3c) 

sleep suspend execution for interval .sleep(3c) 

acos, dacos Fortran arccosine intrinsic function .acos(3f) 

aint, dint Fortran integer part intrinsic function .aint(3f) 

asin, dasin Fortran arcsine intrinsic function .asin(3f) 

datan2 Fortran arctangent intrinsic function atan2, . . . ..atan2(3f) 

atan, datan Fortran arctangent intrinsic function .atan(3f) 

Fortran complex conjugate intrinsic function /dconjg .conjg(3f) 

cos, dcos, ccos Fortran cosine intrinsic function .cos(3f) 

dcosh Fortran hyperbolic cosine intrinsic function cosh,.cosh(3f) 

dprod double precision product intrinsic function .dprod(3f) 

dexp, cexp Fortran exponential intrinsic function exp,.exp(3f) 

dloglO Fortran common logarithm intrinsic function /aloglO,.Iogl0(3f) 

clog Fortran natural logarithm intrinsic function /alog, dlog,.log(3f) 

dsign Fortran transfer-of-sign intrinsic function sign, isign,.sign(3f) 

sin, dsin, csin Fortran sine intrinsic function .sin(3f) 

dsinh Fortran hyperbolic sine intrinsic function sinh,.sinh(3f) 

csqrt Fortran square root intrinsic function sqrt, dsqrt,.sqrt(3f) 

tan, dtan Fortran tangent intrinsic function .tan(3f) 

Fortran hyperbolic tangent intrinsic function tanh, dtanh .tanh(3f) 

ddim, idim positive difference intrinsic functions dim, .dim(3f) 

lgt, lie, lit string comparison intrinsic functions lge,.lge(3f) 

amod, dmod Fortran remaindering intrinsic functions mod, ..mod(3f) 

formats intro introduction to file .intro{4) 

miscellany intro introduction to ..intro(51 

subroutines and libraries intro introduction to.intro(3) 

calls and error numbers intro introduction to system.intro(2) 

intro introduction to file formats.intro(4) 

intro introduction to miscellany .intro(5i 

libraries intro introduction to subroutines and.intro(3) 

error numbers intro introduction to system calls and ...... intro(2) 

ioctl control device.ioctl(2) 

ishftc, ibits, btest, ibset,/ ior, iand, not, ieor, ishft,.ior(3f) 

abort generate an 10T fault .. abort(3c) 

number generator irand, rand, srand random .irand(3f) 

/islower, isdigit, isxdigit, isalnum, isspace, ispunct,/ .isalpha(3c) 

isdigit, isxdigit, isalnum,/ isalpha, isupper, islower,.isalpha(3c) 
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/isprint, isgraph, iscntrl, 
ttyname, 
/ispunct, isprint, isgraph, 
isalpha, isupper, islower, 
/isspace, ispunct, isprint, 
ibset,/ ior, iand, not, ieor, 
ior, iand, not, ieor, ishft, 
t ransfer-of-sign intrinsic/ sign, 
isalnum,/ isalpha, isupper, 
/isalnum, isspace, ispunct, 
/isxdigit, isalnum, isspace, 
/isdigit, isxdigit, isalnum, 

system 
Fortran system 
issue 

isxdigit, isalnum,/ isalpha, 
/isupper, islower, isdigit, 
functions 
functions jO, 
jO, jl, 

/irand48, nrand48, mrand48, 
or a group of processes 
3-byte integers and long/ 
integer and base-64 ASCII/ a64l, 
/jrand48, srand48, seed48, 
file ldclose, 

header of a member of an archive/ 
file for reading Idopen, 
common object file 
floating-point numbers frexp, 
routines 
of a common object file 
for common object file symbol/ 
line number entries of/ ldlread, 
entries of a/ ldlread, ldlinit, 
manipulate line number entries/ 
number entries of a section of a/ 
entries of a section of/ ldlseek, 
entries of a section of/ Idrseek, 
section header of a/ ldshread, 
named section of a/ Idsseek, 
file header of a common object/ 
object file for reading 
relocation entries of a section/ 
indexed named section header of/ 
indexed named section of a/ 
a symbol table entry of a common/ 
table entry of a common object/ 
table of a common object file 
string 
len return 
getopt get option 
lsearch, 

comparison intrinsic functions 
intrinsic functions lge, 
introduction to subroutines and 
ulimit get and set user 
return the number of command 
establish an out-going terminal 


isascii classify characters ........ isalpha(3c) 


isafcty find name of a terminal ...... ttyname(3c) 

iscntrl, isascii classify/ ......... isalpha(3c) 

isdigit, isxdigit, isalnum,/ ....*•••• isalpha(3c) 

isgraph, iscntrl, isascii/ * . -.isalpha(3c) 

ishft, ishftc, ibits, btest, ......... ior(3f) 

ishftc, ibits, btest, ibset,/ • « . ..ior(3f) 

isign, dsign Fortran . . ..sign(3f) 

islower, isdigit, isxdigit, isalpha(3c) 

isprint, isgraph, iscntrl,/ ......... isalpha(3cj 

ispunct, isprint, isgraph,/ isalpha(3c) 

isspace, ispuKt, isprint,/.. isalpha(3c) 

issue issue identification file.issue(4) 

issue a shell command.. system(3s) 

issue a shel! command from ~ .system(3f) 

issue identification file .......... issue(4) 

isupper, Mower, isdigit, .. isalpha(3c) 

isxdigit, isalnum, isspace,/ ........ isalpha(3c) 

jO, jl, jn, yO, yl, yn Bessel .j0(3m) 

jl, jn, yO, yl, yn Bessel.j0(3m) 

jn, yO, yl, yn Bessel functions ...... j0(3m) 

jrand48, srand48, seed48, Jcong48/.drand48(3c) 

kill send a signal to a process ...... kill(2) 

l3tol, ltol3 convert between . ..13tol(3c) 

164a convert between long ..a64l(3c) 

lcong48 generate uniformly/ ....... drand48(3c) 

ldaclose close a com»on object .ldclose(3x) 

ldahread read the archive.ldahread(3x) 

ldaopen open a common object .ldopen(3xl 

ldclose, ldaclose close a ..ldclose(3x) 

ldexp, modf manipulate parts of.frexp(3c) 

ldfcn common object file access .ldfcn(4) 

Idfhread read the file header .ldfhread(3x) 

ldgetname retrieve symbol name ..... ldgetname(3x) 

ldlinit, ldlitem manipulate .ldlread(3x) 

ldlitem manipulate line number.ldlread(3x) 

ldlread, ldlinit, ldlitem ..ldlread(3x) 

ldlseek, ldnlseek seek to line . ..ldlseek(3x) 

ldnlseek seek to line number ....... ldlseek(3x) 

ldnrseek seek to relocation .ldrseek(3x) 

ldnshread read an indexed named .... ldshread(3x) 

ldnsseek seek to an indexed.ldsseek(3x) 

Jdohseek seek to the optional .ldobseek(3x) 

Idopen, ldaopen open a common.ldopen(3x) 

Idrseek, ldnrseek seek to . ..ldrseek(3x) 

ldshread, ldnshread read an ....... ldshread(3x) 

Idsseek, ldnsseek seek to an . ..ldsseek(3x) 

Idtbindex compute the index of .ldtbindex(3x) 

ldtbread read an indexed symbol.ldtbread(3x) 

ldtbseek seek to the symbol ldtbseek(3x) 

len return length of Jbrtran ..len(3f) 

length of Fortran string . ..len(3f) 

letter from argument vector .getopt(3c) 

Ifind linear search and update.lsearch(3c) 

lge, Igt, lie, lh string.lge(3f) 

lgt, lie, lit string comparison.lge(3f) 

libraries intro .intro(3) 

limits .ulimit(2) 

line arguments iargc .iargc(3f) 

line connection dial • • . ..dial(3c) 
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object file linenum line number entries in a common .linenum(4) 

/ldlinit, ldlitem manipulate line number entries of a common/.ldlread(3x) 

of a/ Idlseek, ldnlseek seek to line number entries of a section.ldlseek(3x) 

lsearch, lfind linear search and update.lsearch(3c) 

a common object file linenum line number entries in.linenum(4) 

link link to a file.link(2) 

/a.out common assembler and link editor output.. . a.out(4) 

link link to a file .link(2) 

nlist get entries from name list .nlist(3c) 

handle variable argument list varargs .varargs(5) 

output of a varargs argument list /vsprintf print formatted ..vprintff3s) 

output of a varargs argument list /vsprintf print formatted.vprintf(3x) 

fsck checklist list of file systems processed by ♦.checklist(4) 

dosdisks list of MPS/DOS virtual disks .* dosdisks(4) 

smile disks list of SMILE virtual disks.smiledisks(4) 

intrinsic functions Ige, lgt, lie, lit string comparison .. lge(3fl 

functions lge, lgt, lie, lit string comparison intrinsic.lge(3f) 

convert date and time/ ctime, localtime, gmtime, asctime, tzset .ctime(3c) 

index return location of Fortran substring.index(3f) 

end, etext, edata last locations in program.end(3c) 

memory plock lock process, text, or data in.plock(2) 

lockf record locking on files.lockf(3cl 

iockf record locking on files .lockf(3c) 

natural logarithm intrinsic/ log, alog, dlog, clog Fortran ..log(3f) 

gamma log gamma function . • . . ..gamma(3m) 

exponential, logarithm,/ exp, log, loglO, pow, sqrt . • . . ..exp(3m) 

common logarithm intrinsic/ loglO, aloglO, dloglO Fortran .Iogl0(3f) 

logarithm, power,/ exp, log, loglO, pow, sqrt exponential, .exp(3m) 

/aloglO, dloglO Fortran common logarithm intrinsic function.Iogl0(3f) 

/dlog, clog Fortran natural logarithm intrinsic function.log(3f) 

/loglO, pow, sqrt exponential, logarithm, power, square root/ exp(3m) 

getlogin get login name.getlogin(3c) 

cuserid get character login name of the user.cuserid(3s) 

logname return login name of user.logname(3x) 

setting up an environment at login time profile .. profile(4) 

user logname return login name of.logname(3x) 

setjmp, longjmp non-local goto.setjmp(3c) 

jrand48,/ drand48, erand48, lrand48, nrand48, mrand48,.drand48(3c) 

and update lsearch, lfind linear search.lsearch(3c) 

pointer lseek move read/write file.lseek(2) 

Boolean/ and, or, xor, not, lshift, rshift Fortran Bitwise.and(3f) 

integers and long/ 13tol, ltol3 convert between 3-byte .l3tol(3c) 

values machine-dependent values .values(5) 

/access long integer data in a machine-independent fashion.sputl(3x) 

malloc, free, realloc, calloc main memory allocator • . . ..malloc(3c) 

calloc, mallopt, mallinfo fast main memory allocator /realloc, .malloc(3xl 

/free, realloc, calloc, mallopt, mallinfo fast main memory/.malloc(3x) 

main memory allocator malloc, free, realloc, calloc.malloc(3c) 

mallopt, mallinfo fast main/ malloc, free, realloc, calloc,.malloc (3x1 

malloc, free, realloc, calloc, mallopt, mallinfo fast main/ .malloc(3x) 

tsearch, tfind, tdelete, twalk manage binary search trees.tsearch(3c) 

hsearch, hcreate, hdestroy manage hash search tables.hsearch(3c) 

a/ ldlread, ldlinit, ldlitem manipulate line number entries of.ldlread(3x) 

frexp, ldexp, modf manipulate parts of/ .frexp(3c) 

ascii map of ASCII character set.ascii(5) 

umask set and get file creation mask .umask(2) 

regular expression compile and match routines regexp .regexp(5) 

constants math math functions and.math(5) 

math math functions and constants.math(5) 

matherr error-handling function.matherr(3m) 
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dm&xl Fortran maximum-value/ max, maxO, amaxO, maxi, amaxl,.maxf3f) 

Fortran maximum-value/ max, maxO, amaxO, maxi, amaxl, dmaxl ♦ . . . max(3f) 

maximum-value/ max, maxO, amaxO, maxi, amaxl, dmaxl Fortran.max(3f) 

maxi, amaxl, dmaxl Fortran maximum-value functions /amaxO, . . . . max(3f) 

accounting mclock return Fortran time.mclock(3f) 

/read the archive header of a member of an archive file.ldahread(3x) 

memset memory operations memccpy, memchr, memcmp, memcpy, . . . memccpyf3c) 

memory operations memccpy, memchr, memcmp, memcpy, memset .... memccpy(3c) 

operations memccpy, memchr, memcmp, memcpy, memset memory • • • memccpy(3c) 

memccpy, memchr, memcmp, memcpy, memset memory/ .memccpy(3c) 

lock process, text, or data in memory plock .plock(2) 

free, realloc, calloc main memory allocator malloc, .. malloe(3c) 

mallopt, mallinfo fast main memory allocator /calloc, ..malloc(3x) 

shmctl shared memory control operations.shmctl(2) 

core format of memory image file.. ..core(4) 

memchr, memcmp, memcpy, memset memory operations memccpy,.memccpy(3c) 

shmop shared memory operations .shmop(2) 

shmget get shared memory segment .shmget(2) 

memccpy, memchr, memcmp, memcpy, memset memory operations.memccpy(3c) 

msgctl message control operations.msgctl(2) 

msgop message operations • ..msgop(2) 

msgget get message queue .msgget(2) 

sys_nerr system error messages /errno, sys^errlist, .perror(3c) 

dminl Fortran minimum-value/ min, minO, aminO, mini, aminl,.min(3n 

Fortran minimum-value/ min, minO, aminO, mini, aminl, dminl.min(3fi 

minimum-value/ min, minO, aminO, mini, aminl, dminl Fortran.min(3f) 

mini, aminl, dminl Fortran minimum-value functions /aminO, ..... min(3f) 

intro introduction to miscellany .intro(5) 

special or ordinary file mknod make a directory, or a.mknod(2) 

mktemp make a unique file name .... mktemp(3c) 

table mnttab mounted file system.mnttab(4) 

remaindering intrinsic functions mod, amod, dmod Fortran ..mod(3f) 

chmod change mode of file.chmod(2) 

floating-point/ frexp, ldexp, modf manipulate parts of.frexp(3c) 

utime set file access and modification times.utime(2) 

profile monitor prepare execution .. monitor(3c) 

mount mount a file system .mount(2) 

mount mount a file system .mount(2) 

mnttab mounted file system table .mnttab(4) 

lseek move read/write file pointer .. lseek(2) 

dosdisks list of MPS/DOS virtual disks .dosdisks(4) 

/erand48, lrand48, nrand48, mrand48, jrand48, srand48,/.drand48(3c) 

operations msgctl message control.. msgctl(2) 

msgget get message queue.msgget(2) 

msgop message operations •••..••• msgop(2) 

information mttys Multi-Link partition .mttys(4) 

mttys Multi-Link partition information .mttys(4) 

ibits, btest, ibset, ibclr, mvbits bit /ishft, ishftc, .ior(3f) 

return value for environment name getenv .getenv(3c) 

getlogin get login name .. getlogin(3c) 

mktemp make a unique file name .mktemp(3c) 

tmpnam, tempnam create a name for a temporary file .tmpnam(3s) 

ldgetname retrieve symbol name for common object file/.ldgetname(3x) 

ctermid generate file name for terminal.ctermid(3s) 

getpw get name from UID.getpw(3c) 

nlist get entries from name list ...nlist(3c) 

ttyname, isatty find name of a terminal .ttyname(3c) 

uname get name of current UNIX system ....... uname(2) 

cuserid get character login name of the user . . ..cuserid(3s) 

logname return login name of user.. ..logname(3x) 
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/Idnshread read an indexed named section header of a common/ .... ldshread(3x) 
/Idnsseek seek to an indexed named section of a common object/ .... ldsseek(3x) 

term conventional names for terminals • ..term(5) 

log, alog, dlog, clog Fortran natural logarithm intrinsic/ .log(3f) 

dnint, nint, idnint Fortran nearest integer functions anint, ...... anint(3f) 

process nice change priority of a .nice(2) 

integer functions anint, dnint, nint, idnint Fortran nearest.anint(3f) 

list nlist get entries from name .nli$t(3c) 

setjmp, longjmp non-local goto.setjmp(3c) 

btest, ibset, ibclr,/ ior, iand, not, ieor, ishft, ishftc, ibits,.ior(3f) 

Bitwise Boolean/ and, or, xor, not, lshift, rshift Fortran.and(3f) 

drand48, erand48, lrand48, nrand48, mrand48, jrand48,/.. • drand48(3c) 

string to double-precision number strtod, atof convert.strtod(3c) 

file linenum line number entries in a common object .... linenum(4) 

file/ /ldlitem manipulate line number entries of a common object • • • • ldlread(3x) 

ldlseek, Idnlseek seek to line number entries of a section of a/ • • . • • ldlseek(3x) 

irand, rand, srand random number generator ..irand(3f) 

iargc return the number of command line arguments .... iargc(3f) 
gcvt convert floating-point number to string ecvt, fcvt, ....... ecvt(3c) 

distributed pseudorandom numbers /generate uniformly.drand48(3c) 

parts of floating-point numbers /ldexp, modf manipulate .... frexp(3c) 

to system calls and error numbers intro introduction . ..intro(2) 

ldaclose close a common object file ldclose,.. ldclose(3x) 

read the file header of a common object file ldfhread .ldfhread(3x) 

entries of a section of a common object file /seek to line number.ldlseek(3x) 

optional file header of a common object file /seek to the.ldohseek(3x) 

entries of a section of a common object file /seek to relocation.ldrseek(3x) 

named section header of a common object file /read an indexed .ldshread(3x) 

indexed named section of a common object file /seek to an.ldsseek(3x) 

a symbol table entry of a common object file /compute the index of.ldtbindex(3x) 

symbol table entry of a common object file /read an indexed .ldtbread(3x) 

to the symbol table of a common object file ldtbseek seek .ldtbseek(3x) 

line number entries in a common object file linenum •••••...•.. linenum(4) 

information for a common object file reloc relocation .reloc(4) 

section header for a common object file scnhdr .scnhdr(4) 

ldfcn common object file access routines.ldfcn(4) 

ldopen, ldaopen open a common object file for reading .ldopen(3x) 

line number entries of a common object file function /manipulate.ldlread(3x) 

/retrieve symbol name for common object file symbol table entry.ldgetname(3x) 

syms common object file symbol table format .syms(4) 

filehdr file header for common object files.filehdr(4) 

writing open open for reading or .open(2) 

reading ldopen, ldaopen open a common object file for.ldopen(3x) 

fopen, freopen, fdopen open a stream .fopen(3s) 

dup duplicate an open file descriptor .dup(2) 

open open for reading or writing.open(2) 

seekdir, rewinddir,/ directory: opendir, readdir, telldir, .directory:(3x) 

rewinddir, closedir directory operations /telldir, seekdir,.directory:(3x) 

memcmp, memcpy, memset memory operations memccpy, memchr, .memccpy(3c) 

msgctl message control operations .msgctl(2) 

msgop message operations .msgop(2) 

semctl semaphore control operations .semctl(2) 

semop semaphore operations .semop(2j 

shmctl shared memory control operations .shmctl(2) 

shmop shared memory operations .. shmop(2) 

strspn, strcspn, strtok string operations /strrchr, strpbrk,.strcat(3c) 

curses CRT screen handling and optimization package .curses(3x) 

vector getopt get option letter from argument .getopt(3c) 

object/ ldohseek seek to the optional file header of a common .ldohseek(3x) 

fcntl file control options ..fcntl(5) 
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Fortran Bitwise Boolean/ and, or, xor, not, Ishift, rshift.and(3f) 

make a directory, or a special or ordinary file mknod .mknod(2) 

connection dial establish an out-going terminal line.dial(3c) 

common assembler and link editor output /a.out . . ..a.out(4) 

sprintf print formatted output printf, fprintf,.printf(3s) 

/destinations for spooled output from SLPT printers.dosprinters(4) 

/vsprintf print formatted output of a varargs argument list.vprintf(3s) 

/vsprintf print formatted output of a varargs argument list.vprintf(3x) 

OVRIDE bit ovride set/clear hardware ..ovridef2l 

ovride set/clear hardware OVRIDE bit • . . . •.ovride(2) 

chown change owner and group of a file.cbown(2) 

screen handling and optimization package curses CRT.curses(3x) 

interprocess communication package ftok standard.ftok(3c) 

standard buffered input/output package stdio .stdio(3s) 

get process, process group, and parent process IDs /getppid .getpid(2) 

aint, dint Fortran integer part intrinsic function.. . . aint(3f) 

aimag, dimag Fortran imaginary part of complex argument .aimag(3f) 

mttys Multi-Link partition information •.mttys(4) 

frexp, Idexp, modf manipulate parts of floating-point numbers.frexp(3c) 

passwd password file.passwd(4) 

getpass read a password.getpass(3c) 

passwd password file .passwd(4) 

endpwent, fgetpwent get password file entry /setpwent, .getpwent(3c) 

putpwent write password file entry .putpwent(3c) 

directory getcwd get path-name of current working ...... getcwd(3c) 

signal pause suspend process until.pause(2) 

process popen, pclose initiate pipe to/from a ...... popen(3s) 

format acct per-process accounting file .acct(4) 

sys_nerr system error messages perror, errno, sys_errlist,.perror(3c) 

channel pipe create an interprocess .pipe(2) 

popen, pclose initiate pipe to/from a process.popen(3s) 

data in memory plock lock process, text, or .plock(2) 

plot graphics interface.plotU) 

subroutines plot graphics interface .plot(3x) 

lseek move read/write file pointer.. lseek(2) 

rewind, ftell reposition a file pointer in a stream fseek, .fseek(3s) 

to/from a process popen, pclose initiate pipe.popen(3s) 

functions dim, ddim, idim positive difference intrinsic . ..dim(3f) 

logarithm,/ exp, log, loglO, pow, sqrt exponential, .exp(3ml 

/sqrt exponential, logarithm, power, square root functions .exp(3m) 

function dprod double precision product intrinsic .dprod(3f) 

monitor prepare execution profile.. monitor(3c) 

graphical files gps graphical primitive string, format of ..gps(4) 

types primitive system data types .types(5) 

printf, fprintf, sprintf print formatted output ..printf(3s) 

vprintf, vfprintf, vsprintf print formatted output of a/.vprintf(3s) 

vprintf, vfprintf, vsprintf print formatted output of a/.vprintf(3x) 

for spooled output from SLPT printers /destinations.dosprinters(4) 

formatted output printf, fprintf, sprintf print.printf(3s) 

nice change priority of a process.nice(2) 

exit, _exit terminate process ....... .exit(2) 

fork create a new process.... fork(2) 

inittab script for the init process.inittab(4) 

nice change priority of a process.nice(2) 

pclose initiate pipe to/from a process popen, .popen(3s) 

acct enable or disable process accounting.acct(2) 

alarm set a process alarm clock .alarm(2) 

times get process and child process times.times(2) 

/getpgrp, getppid get process, process group, and parent process/ .... getpid(2) 

setpgrp set process group ID .setpgrp(2) 
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process group, and parent process IDs /get process,.getpid(2) 

kill send a signal to a process or a group of processes .kill(2) 

getpid, getpgrp, getppid get process, process group, and/ .getpid(2) 

plock lock process, text, or data in memory .plockf2) 

times get process and child process times.times(2) 

wait wait for child process to stop or terminate .wait(2) 

ptrace process trace..ptrace(2) 

pause suspend process until signal .. . . . pause(2) 

checklist list of file systems processed by fsck .checklist(4) 

signal to a process or a group of processes kill send a ..kill(2) 

dprod double precision product intrinsic function .dprod(3f) 

prof profile within a function .prof(5) 

profit execution time profile.profil(2) 

monitor prepare execution profile.monitor(3c) 

profit execution time profile.profil(2) 

environment at login time profile setting up an .profile(4) 

prof profile within a function.prof(5) 

abort terminate Fortran program . . . . ..abort(3f) 

etext, edata last locations in program end,.end(3c) 

assert verify program assertion.assert(3x) 

generate uniformly distributed pseudo-random numbers /lcong48 . . • . drand48(3c) 

ptrace process trace ..ptrace(2) 

stream ungetc push character back into input.ungetc(3s) 

puts, fputs put a string on a stream.puts(3s) 

putc, putchar, fputc, putw put character or word on a stream .... putc(3s) 

character or word on a stream putc, putchar, fputc, putw put.putc(3s) 

character or word on a/ putc, putchar, fputc, putw put.putc(3sj 

environment putenv change or add value to.putenv(3c) 

entry putpwent write password file .putpwent(3c) 

stream puts, fputs put a string on a.puts(3s) 

getutent, getutid, getutline, pututline, setutent, endutent,/ .getutent(3c) 

stream putc, putchar, fputc, putw put character or word on a .... putc(3s) 

qsort quicker sort . ..q$ort(3c) 

msgget get message queue .msgget(2) 

qsort quicker sort.. qsort(3c) 

generator irand, rand, srand random number.irand(3f) 

random-number generator rand, srand simple ... rand(3c) 

irand, rand, srand random number generator .irand(3f) 

rand, srand simple random-number generator .rand(3c) 

read read from file.read(2) 

getpass read a password . ..getpass(3c) 

header of a/ ldshread, ldnshread read an indexed named section.ldshread(3x) 

entry of a common/ ldtbread read an indexed symbol table.ldtbread(3x) 

read read from file.read(2) 

member of an archive/ ldahread read the archive header of a .ldahread(3x) 

object file ldfhread read the file header of a common.ldfhread(3x) 

rewinddir,/ directory: opendir, readdir, telldir, seekdir, . directory:(3x) 

open a common object file for reading ldopen, ldaopen .ldopen(3x) 

open open for reading or writing.open(2) 

Iseek move read/write file pointer.lseek(2) 

dcmplx, ichar,/ int, ifix, idint, real, float, sngl, dble, cmplx, ..int(3f) 

/get real user, effective user, real group, and effective group/.getuid(2| 

/geteuid, getgid, getegid get real user, effective user, real/.getuid(2) 

allocator malloc, free, realloc, calloc main memory.malloc(3c) 

mallinfo fast/ malloc, free, realloc, calloc, mallopt, .malloc(3x) 

signal specify what to do upon receipt of a signal.signal(2) 

/specify Fortran action on receipt of a system signal.signal(3f) 

lockf record locking on files .lockf(3c) 

execute regular expression regcmp, regex compile and .regcmp(3x) 

regular expression regcmp, regex compile and execute.regcmp(3x) 
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compile and match routines regexp regular expression.regexp(5) 

regex compile and execute regular expression regcmp,.regcmp(3x) 

match routines regexp regular expression compile and .regexp(5) 

for a common object file reloc relocation information.reloc(4) 

of a/ ldrseek, Idnrseek seek to relocation entries of a section.ldrseek(3x) 

common object file reloc relocation information for a .reloc(4) 

fmod, fabs floor, ceiling, remainder, absolute value/ /ceil,.floor(3m) 

mod, amod, dmod Fortran remaindering intrinsic functions.mod(3f) 

unlink remove directory entry . ..unlink(2) 

clock report CPU time used.clock(3c) 

stream fseek, rewind, ftell reposition a file pointer in a .fseek(3s) 

object file symbol/ ldgetname retrieve symbol name for common . . . . • ldgetname(3x) 

argument getarg return Fortran command-line.getarg(3f) 

variable getenv return Fortran environment .. getenv(3f) 

me lock return Fortran time accounting.mclock(3f) 

abs return integer absolute value.abs(3c) 

len return length of Fortran string.len(3fl 

substring index return location of Fortran .index(3f) 

logname return login name of user.logname(3x) 

arguments iarge return the number of command line .... iargc(3f) 

getenv return value for environment name .... getenv(3c) 

stat data returned by stat system call .stat(5) 

pointer in a stream fseek, rewind, ftell reposition a file.fseek(3s) 

/readdir, telldir, seekdir, rewinddir, closedir directory/ .directory:(3x) 

creat create a new file or rewrite an existing one.creat(2) 

chroot change root directory.chroot(2) 

logarithm, power, square root functions /exponential, .exp(3m) 

dsqrt, csqrt Fortran square root intrinsic function sqrt,.sqrt(3f) 

ldfcn common object file access routines .ldfcn(4l 

expression compile and match routines regexp regular.regexp(5) 

and, or, xor, not, Ishift, rshift Fortran Bitwise Boolean/.and(3f) 

uxrc ICON/UXB run-time configuration file .uxrc(4) 

allocation brk, sbrk change data segment space.brk(2) 

formatted input scanf, fscanf, sscanf convert.scanf(3s) 

sccsfile format of SCCS file.sccsfile(4l 

sccsfile format of SCCS file .sccsfile(4) 

common object file scnhdr section header for a .scnhdr(4) 

package curses CRT screen handling and optimization.curses(3x) 

inittab script for the init process.inittab(4) 

bsearch binary search a sorted table .bsearch(3c) 

Isearch, lfind linear search and update.lsearch(3c) 

hcreate, hdestroy manage hash search tables hsearch,.hsearch(3c) 

tdelete, twalk manage binary search trees tsearch, tfind,.tsearch(3c) 

object file scnhdr section header for a common.scnhdr(4) 

/ldnshread read an indexed named section header of a common object/ . . . . ldshread(3x) 

/seek to line number entries of a section of a common object file.ldlseek(3x) 

/seek to relocation entries of a section of a common object file.ldrseek(3x) 

/seek to an indexed named section of a common object file.ldsseek(3x) 

/mrand48, jrand48, srand48, seed48, lcong48 generate/.drand48(3c) 

of a common/ ldsseek, Idnsseek seek to an indexed named section.ldsseek(3x) 

section of a/ ldlseek, ldnlseek seek to line number entries of a.ldlseek(3x) 

section of a/ ldrseek, Idnrseek seek to relocation entries of a.ldrseek(3x) 

of a common object file ldohseek seek to the optional file header.ldohseek(3x) 

common object file ldtbseek seek to the symbol table of a.ldtbseek(3x) 

/opendir, readdir, telldir, seekdir, rewinddir, closedir/ .directory:(3x) 

shmget get shared memory segment .shmget(2) 

brk, sbrk change data segment space allocation ..brk(2) 

semctl semaphore control operations.semctl(2) 

semop semaphore operations .semop(2) 

semget get set of semaphores.semget(2) 
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operations semctl semaphore control.semctl(2) 

semget get set of semaphores ...... semget(2) 

semop semaphore operations.. semop(2) 

group of processes kill send a signal to a process or a .kill(2) 

ascii map of ASCII character set . . . ..ascii(5) 

alarm set a process alarm clock.. . . alarm(2) 

umask set and get file creation mask.umask(2) 

times utime set file access and modification .utime(2) 

semget get set of semaphores.semget(2) 

setpgrp set process group ID.setpgrp(2) 

stime set time .stime(2) 

setuid, setgid set user and group IDs.setuid(2) 

ulimit get and set user limits.ulimit(2) 

buffering to a stream setbuf, setvbuf assign.. setbuf(3s) 

ovride set/clear hardware OVRIDE bit.ovride(2) 

setuid, setgid set user and group IDs ..setuid(2) 

getgrent, getgrgid, getgrnam, setgrent, endgrent, fgetgrent/.getgrent(3c) 

setjmp, longjmp non-local goto . . • . . setjmp(3c) 

encryption crypt, setkey, encrypt generate DES.crypt(3c) 

setpgrp set process group ID.setpgrp(2) 

getpwent, getpwuid, getpwnam, setpwent, endpwent, fgetpwent/.getpwent(3c) 

login time profile setting up an environment at.profile(4) 

gettydefs speed and terminal settings used by getty.gettydefs(4) 

group IDs setuid, setgid set user and.setuid(2) 

/getutid, getutline, pututline, setutent, endutent, utmpname/.getutent(3c) 

stream setbuf, setvbuf assign buffering to a.setbuf(3s) 

in a machine-independent/ sputl, sgetl access long integer data.sputl(3x) 

shmctl shared memory control operations.shmctl(2) 

shmop shared memory operations.shmop(2) 

shmget get shared memory segment .. . shmget(2) 

system issue a shell command .system(3s) 

system issue a shell command from Fortran.system(3f) 

operations shmctl shared memory control.shmctl(2) 

segment shmget get shared memory .shmget(2) 

shmop shared memory operations .... shmop(2) 

transfer-of-sign intrinsic/ sign, isign, dsign Fortran ..sign(3f) 

pause suspend process until signal .pause(2) 

what to do upon receipt of a signal signal specify .signal(2) 

action on receipt of a system signal signal specify Fortran .signal(3f) 

on receipt of a system signal signal specify Fortran action ..signal(3f) 

receipt of a signal signal specify what to do upon.signal(2) 

processes kill send a signal to a process or a group of.kill(2) 

ssignal, gsignal software signals • • • ..ssignal(3c) 

rand, srand simple random-number generator.rand(3c) 

atan2 trigonometric functions sin, cos, tan, asin, acos, atan,.sinf3m) 

intrinsic function sin, dsin, csin Fortran sine .sinf3f) 

sin, dsin, csin Fortran sine intrinsic function .sin(3f) 

sinh, dsinh Fortran hyperbolic sine intrinsic function .sinh(3f) 

functions sinh, cosh, tanh hyperbolic .sinh(3m) 

sine intrinsic function sinh, dsinh Fortran hyperbolic.sinh(3f) 

interval sleep suspend execution for .sleep(3c) 

current user ttyslot find the slot in the utmp file of the .ttyslot(3c) 

for spooled output from SLPT printers /destinations.dosprinters(4) 

smiledisks list of SMILE virtual disks.smiledisks(4) 

virtual disks smiledisks list of SMILE ........ smiledisks(4) 

int, ifix, idint, real, float, sngl, dble, cmplx, dcmplx, ichar,/.int(3f) 

' ssignal, gsignal software signals.. . ssignal(3c) 

qsort quicker sort.qsort(3c) 

bsearch binary search a sorted table .bsearch(3c) 

brk, sbrk change data segment space allocation.brk(2) 
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mknod make a directory, or a special or ordinary file.mknod(2) 

fspec format specification in text files.fspec(4) 

of a system signal signal specify Fortran action on receipt .signalf3f) 

of a signal signal specify what to do upon receipt.signal(2) 

by getty gettydefs speed and terminal settings used .gettydefs(4) 

dosprinters destinations for spooled output from SLPT printers . . ♦ . dosprinters(4) 

printf, fprintf, sprintf print formatted output.printf(3s) 

integer data in a/ sputl, sgetl access long.sputl(3x) 

power,/ exp, log, loglO, pow, sqrt exponential, logarithm,.exp(3m) 

square root intrinsic function sqrt, dsqrt, csqrt Fortran.sqrt(3f) 

exponential, logarithm, power, square root functions /sqrt ....... exp(3m) 

sqrt, dsqrt, csqrt Fortran square root intrinsic function.sqrt(3f) 

irand, rand, srand random number generator.irand(3f) 

generator rand, srand simple random-number ...... rand(3c) 

/nrand48, mrand48, jrand48, srand48, seed48, lcong48/.drand48(3c) 

scanf, fscanf, sscanf convert formatted input .scanf(3s) 

signals ssignal, gsignal software .ssignal(3c) 

package stdio standard buffered input/output.stdio(3s) 

communication package ftok standard interprocess .ftok(3c) 

system call stat data returned by stat .stat(5) 

stat, fstat get file status .stat(2) 

stat data returned by stat system call ♦ . . . ..stat(5) 

ustat get file system statistics.ustat(2) 

stat, fstat get file status.stat(2) 

feof, clearerr, fileno stream status inquiries Terror,.ferror(3s) 

input/output package stdio standard buffered.stdio(3s) 

stime set time.stime(2) 

wait wait for child process to stop or terminate.wait(2) 

strcpy, strncpy, strlen, strchr,/ strcat, strncat, strcmp, strncmp, .strcat(3c) 

/strncmp, strcpy, strncpy, strlen, strchr, strrchr, strpbrk, strspn,/.strcat(3c) 

strlen, strchr,/ strcat, strncat, strcmp, strncmp, strcpy, strncpy, .strcat(3cj 

strcat, strncat, strcmp, strncmp, strcpy, strncpy, strlen, strchr,/ ...... strcat(3c) 

strchr, strrchr, strpbrk, strspn, strcspn, strtok string/ /strlen,.strcat(3c) 

fclose, fflush close or flush a stream.fclose(3s) 

fopen, freopen, fdopen open a stream.fopen(3s) 

reposition a file pointer in a stream fseek, rewind, ftell .fseek(3s) 

get character or word from a stream /getchar, fgetc, getw .getc(3s) 

gets, fgets get a string from a stream.gets(3s) 

putw put character or word on a stream putc, put char, fputc,.putc(3s) 

puts, fputs put a string on a stream ..puts(3s) 

setvbuf assign buffering to a stream setbuf, .setbuf(3s) 

push character back into input stream ungetc ..ungetc(3s) 

Terror, feof, clearerr, fileno stream status inquiries.ferror(3s) 

long integer and base-64 ASCII string /164a convert between .a64l(3c) 

tzset convert date and time to string /gmtime, asctime,.ctime(3c) 

convert floating-point number to string ecvt, fcvt, gcvt .ecvt(3c) 

len return length of Fortran string ...len(3f) 

functions lge, Igt, He, lit string comparison intrinsic.lg;e(3f) 

gps graphical primitive string, format of graphical files.gps(4) 

gets, fgets get a string from a stream.gets(3s) 

puts, fputs put a string on a stream...puts(3s) 

strpbrk, strspn, strcspn, strtok string operations /strrchr, . ..strcat(3c) 

strtod, atof convert string to double-precision number ..... strtod(3c) 

strtol, atol, atoi convert string to integer.strtol(3c) 

/strcmp, strncmp, strcpy, strncpy, strlen, strchr, strrchr, strpbrk,/.strcat(3c) 

strncpy, strlen, strchr,/ strcat, strncat, strcmp, strncmp, strcpy, .strcat(3c) 

strchr,/ strcat, strncat, strcmp, strncmp, strcpy, strncpy, strlen,.strcatfoc) 

/strncat, strcmp, strncmp, strcpy, strncpy, strlen, strchr, strrchr,/ ...... strcat(3c) 

/strncpy, strlen, strchr, strrchr, strpbrk, strspn, strcspn, strtok/.strcat(3c) 

/strcpy, strncpy, strlen, strchr, strrchr, strpbrk, strspn,/.strcat(3c) 
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/strlen, strchr, strrchr, strpbrk, strspn, strcspn, strtok string/.strcat(3c) 

double-precision number strtod, atof convert string to ..strtod(3c) 

/strpbrk, strspn, strcspn, strtok string operations.strcat(3c) 

string to integer strtol, atoi, atoi convert .strtol(3c) 

plot graphics interface subroutines.plot(3x) 

intro introduction to subroutines and libraries.intro(3) 

return location of Fortran substring index .index(3f) 

sync update super-block.sync(2) 

sleep suspend execution for interval.. . sleep(3c) 

pause suspend process until signal.pause(2) 

swab swap bytes.swab(3cl 

swab swap bytes • . . ..swab(3c) 

file swrite synchronous write on a.swrite(2) 

file symbol/ ldgetname retrieve symbol name for common object .ldgetname(3x) 

name for common object file symbol table entry /symbol .ldgetname(3x) 

object/ /compute the index of a symbol table entry of a common .ldtbindex(3x) 

ldtbread read an indexed symbol table entry of a common/.ldtbread(3x) 

syms common object file symbol table format.syms(4) 

file ldtbseek seek to the symbol table of a common object.ldtbseek(3x) 

table format syms common object file symbol.syms(4) 

sync update super-block . ..sync(2) 

swrite synchronous write on a file.swrite(2) 

error messages perror, errno, sys_errlist, sys_nerr system .perror(3cl 

perror, errno, sys_errlist, sysjaerr system error messages .perror(3c) 

mount mount a file system.mount(2) 

umount unmount a file system.umount(2) 

uname get name of current UNIX system.uname(2) 

system issue a shell command.system(3s) 

from Fortran system issue a shell command.system(3f) 

stat data returned by stat system call • . ..stat(5) 

intro introduction to system calls and error numbers.intro(2) 

types primitive system data types.types(5) 

errno, sys^errlist, sysjierr system error messages perror,.perror(3c) 

Fortran action on receipt of a system signal signal specify.signal(3f) 

ustat get file system statistics.ustat(2) 

mnttab mounted file system table • . . . ..mnttab(4) 

fs format of file system volume . ........ fs(4) 

checklist list of file systems processed by fsck.. . checklist(4) 

bsearch binary search a sorted table.bsearch(3c) 

mnttab mounted file system table.mnttab(4) 

for common object file symbol table entry /retrieve symbol name .... ldgetname(3x) 

/compute the index of a symbol table entry of a common object/ .ldtbindex(3x) 

ldtbread read an indexed symbol table entry of a common object/ .ldtbread(3x) 

syms common object file symbol table format ..syms(4) 

ldtbseek seek to the symbol table of a common object file.ldtbseek(3x) 

hdestroy manage hash search tables hsearch, hcreate, .hsearch(3c) 

trigonometric/ sin, cos, tan, asin, acos, atan, atan2.sin(3m) 

intrinsic function tan, dtan Fortran tangent .tan(3f) 

tan, dtan Fortran tangent intrinsic function .. • tan(3f) 

tanh, dtanh Fortran hyperbolic tangent intrinsic function .. tanh(3f) 

sinh, cosh, tanh hyperbolic functions.sinh(3m) 

tangent intrinsic function tanh, dtanh Fortran hyperbolic .tanh(3f) 

search trees tsearch, tfind, tdelete, twalk manage binary.tsearch(3c) 

directory: opendir, readdir, telldir, seekdir, rewinddir,/.directory:(3x) 

temporary file tmpnam, tempnam create a name for a.tmpnam(3s) 

tmpfile create a temporary file.. . tmpfile(3s) 

tempnam create a name for a temporary file tmpnam,.tmpnam(3s) 

terminals term conventional names for .term(5) 

file, term format of compiled term.term(4) 

term format of compiled term file.term(4) 
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data base termcap terminal capability.termcap(4) 

ctermid generate file name for terminal •.ctermid(3s) 

ttyname, isatty find name of a terminal.ttyname(3c) 

termcap terminal capability data base.termcap(4) 

terminfo terminal capability data base.terminfo(4) 

dial establish an out-going terminal line connection.dial(3c) 

gettydefs speed and terminal settings used by getty.gettydefs(4) 

term conventional names for terminals.. . * . term(5) 

wait for child process to stop or terminate wait .wait(2) 

abort terminate Fortran program . . ..abort(3f) 

exit, .exit terminate process.exit(2) 

data base terminfo terminal capability.terminfo(4) 

fspec format specification in text files • • . . ..fspec(4) 

plock lock process, text, or data in memory.plock(2) 

binary search trees tsearch, tfind, tdelete, twalk manage.tsearch(3c) 

get process and child process times times .. . . times(2) 

set file access and modification times utime .utime(2) 

process times times get process and child .times(2) 

tmpfile create a temporary file.tmpfile(3s) 

for a temporary file tmpnam, tempnam create a name . . . . tmpnam(3s) 

/tolower, .toupper, .tolower, toascii translate characters.toupper(3c) 

popen, pclose initiate pipe to/from a process.popen(3s) 

toupper, tolower, .toupper, .tolower, toascii translate/.toupper(3c) 

toascii translate/ toupper, tolower, .toupper, .tolower, .toupper(3cl 

translate/ toupper, tolower, .toupper, .tolower, toascii.toupper(3cj 

.tolower, toascii translate/ toupper, tolower, .toupper,.toupper(3c) 

ptrace process trace . . . ..ptrace(2) 

sign, isign, dsign Fortran transfer-of-sigm intrinsic/.sign(3f) 

.toupper, .tolower, toascii translate characters /tolower, .toupper(3c) 

ftw walk a file tree.ftw(3c) 

twalk manage binary search trees tsearch, tfind, tdelete, .tsearch(3c) 

cos, tan, asin, acos, atan, atan2 trigonometric functions sin, .sin(3m) 

manage binary search trees tsearch, tfind, tdelete, twalk .tsearch(3c) 

terminal ttyname, isatty find name of a • ttyname(3c) 

utmp file of the current user ttyslot find the slot in the ........ ttyslot(3c) 

trees tsearch, tfind, tdelete, twalk manage binary search.tsearch(3c) 

ichar, char explicit Fortran type conversion /cmplx, dcmplx, .int(3f) 

types primitive system data types .types(5) 

types types primitive system data.types(5) 

/localtime, gmtime, asctime, tzset convert date and time to/.ctime(3c) 

getpw get name from UID.getpw(3c) 

ulimit get and set user limits .ulimit(2) 

mask umask set and get file creation .umask(2) 

umount unmount a file system.umount(2) 

system uname get name of current UNIX .... unamef2) 

input stream ungetc push character back into.ungetc(3s) 

seed48, lcong48 generate uniformly distributed/ /srand48, ..... drand48(3c) 

mktemp make a unique file name.mktemp(3c) 

uname get name of current UNIX system.uname(2) 

unlink remove directory entry.unlink(2) 

umount unmount a file system.umount(2) 

pause suspend process until signal.pause(2) 

lfind linear search and update lsearch,.kearch(3c) 

sync update super-block .. sync(2) 

signal specify what to do upon receipt of a signal .signal(2) 

get character login name of the user cuserid .. . cuserid(3s) 

logname return login name of user.logname(3x) 

in the utmp file of the current user ttyslot find the slot .ttyslot(3c) 

setuid, setgid set user and group IDs .setuid(2) 

and/ /getgid, getegid get real user, effective user, real group, .getuid(2) 
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environ user environment .environ(5) 

ulimit get and set user limits ...ulimit(2) 

group/ /get real user, effective user, real group, and effective.getuid(2) 

statistics ustat get file system .ustat(2) 

modification times utime set file access and .utime(2) 

utmp, wtmp utmp and wtmp entry formats ..utmp(4) 

endutent, utmpname access utmp file entry /setutent, .getutent(3c) 

ttyslot find the slot in the utmp file of the current user .ttysiot(3c) 

formats utmp, wtmp utmp and wtmp entry . . . . utmp(4) 

/pututline, setutent, endutent, utmpname access utmp file entry . . * . getutent(3c) 

configuration file uxrc ICON/UXB run-time.uxrc(4) 

abs return integer absolute value .absfSc) 

cabs, sabs Fortran absolute value abs, iabs, dabs, .abs(3f) 

getenv return value for environment name .getenv(3c) 

ceiling, remainder, absolute value functions /fabs floor,.floor(3m) 

putenv change or add value to environment .putenv(3c) 

values machine-dependent values.. . • values(M 

values machine-dependent values .... values(5) 

argument list varargs handle variable.varargs(5) 

print formatted output of a varargs argument list /vsprintf .vprintf(3s) 

print formatted output of a varargs argument list /vsprintf .vprintf(3x) 

return Fortran environment variable getenv .getenv(3f) 

varargs handle variable argument list.varargs(5) 

get option letter from argument vector getopt .getopt(3c) 

assert verify program assertion.assert(3x) 

formatted output of a/ vprintf, vfprintf, vsprintf print .vprintf(3s) 

formatted output of a/ vprintf, vfprintf, vsprintf print .vprintf(3x) 

dosdisks list of MPS/DOS virtual disks .dosdisks(4) 

smiledisks list of SMILE virtual disks .smiledisks(4) 

fs format of file system volume.fs(4) 

print formatted output of a/ vprintf, vfprintf, vsprintf.. . vprintf(3s) 

print formatted output of a/ vprintf, vfprintf, vsprintf.vprintf(3x) 

of a varargs/ vprintf, vfprintf, vsprintf print formatted output.vprintf(3s) 

of a varargs/ vprintf, vfprintf, vsprintf print formatted output.vprintf(3x) 

stop or terminate wait wait for child process to.wait(2l 

terminate wait wait for child process to stop or.wait(2j 

ftw walk a file tree.. ftw(3c) 

prof profile within a function .prof(5) 

fgetc, getw get character or word from a stream /getchar, .getc(3s) 

fputc, putw put character or word on a stream putc, putchar, .putc(3s) 

chdir change working directory.chdir(2) 

getcwd get path-name of current working directory.getcwd(3c) 

write write on a file .write(2) 

swrite synchronous write on a file.... swrite(2) 

write write on a file ..write(2) 

putpwent write password file entry.putpwent(3c) 

open open for reading or writing.open(2) 

formats utmp, wtmp utmp and wtmp entry ..utmp(4) 

utmp, wtmp utmp and wtmp entry formats.utmp(4) 

Fortran Bitwise/ and, or, xor, not, Ishift, rshift . . ..and(3f) 

jO, jl, jn, yO, yl, yn Bessel functions .j0(3m) 

jO, jl, jn, yO, yl, yn Bessel functions.j0(3m) 

jO, jl, jn, yO, yl, yn Bessel functions.j0(3m) 

abs, iabs, dabs, cabs, sabs Fortran absolute value.abs(3f) 
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NAME 

intro — introduction to system calls and error numbers 


SYNOPSIS 

^include <errno.h> 


DESCRIPTION 

This section describes all of the system calls. Most of these calls have one or more 
error returns. An error condition is indicated by an otherwise impossible returned 
value. This is almost always —1; the individual descriptions specify the details. An 
error number is also made available in the external variable errno. Errno is not 
cleared on successful calls, so it should be tested only after an error has been indi¬ 
cated. 

Each system call description attempts to list all possible error numbers. The follow¬ 
ing is a complete list of the error numbers and their names as defined in 
<errno.h>. 

1 EPERM Not owner 

Typically this error indicates an attempt to modify a file in some way forbid¬ 
den except to its owner or super-user. It is also returned for attempts by 
ordinary users to do things allowed only to the super-user. 

2 ENOENT No such file or directory 

This error occurs when a file name is specified and the file should exist but 
doesn’t, or when one of the directories in a path name does not exist. 

3 ESRCH No such process 

No process can be found corresponding to that specified by pid in kill or 
ptrace. 

4 EINTR Interrupted system call 

An asynchronous signal (such as interrupt or quit), which the user has elected 
to catch, occurred during a system call. If execution is resumed after process¬ 
ing the signal, it will appear as if the interrupted system call returned this 
error condition. 

5 EIO I/O error 

Some physical I/O error has occurred. This error may in some cases occur on 
a call following the one to which it actually applies. 

6 ENXIO No such device or address 

I/O on a special file refers to a subdevice which does not exist, or beyond the 
limits of the device. It may also occur when, for example, a tape drive is not 
on-line or no disk pack is loaded on a drive. 

7 E2BIG Arg list too long 

An argument list longer than 5,120 bytes is presented to a member of the 
exec family. 
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8 ENOEXEC Exec format error 

A request is made to execute a file which, although it has the appropriate 
permissions, does not start with a valid magic number [see a.out(4)]. 

9 EBADF Bad file number 

Either a file descriptor refers to no open file, or a read (respectively, write) 
request is made to a file which is open only for writing (respectively, reading). 

10 ECHILD No child processes 

A wait was executed by a process that had no existing or unwaited-for child 
processes. 

11 EAGAIN No more processes 

A fork failed because the system’s process table is full or the user is not 
allowed to create any more processes. 

12 ENOMEM Not enough space 

During an exec, brk, or sbrk, a program asks for more space than the system 
is able to supply. This is not a temporary condition; the maximum space size 
is a system parameter. The error may also occur if the arrangement of text, 
data, and stack segments requires too many segmentation registers, or if 
there is not enough swap space during a fork. 

13 EACCES Permission denied 

An attempt was made to access a file in a way forbidden by the protection 
system. 

14 EFAULT Bad address 

The system encountered a hardware fault in attempting to use an argument 
of a system call. 

15 ENOTBLK Block device required 

A non-block file was mentioned where a block device was required, e.g., in 
mount. 

16 EBUSY Device or resource busy 

An attempt was made to mount a device that was already mounted or an 
attempt was made to dismount a device on which there is an active file (open 
file, current directory, mounted-on file, active text segment). It will also 
occur if an attempt is made to enable accounting when it is already enabled. 
The device or resource is currently unavailable. 

17 EEXIST File exists 

An existing file was mentioned in an inappropriate context, e.g., link. 

18 EXDEV Cross-device link 

A link to a file on another device was attempted. 

19 ENODEV No such device 

An attempt was made to apply an inappropriate system call to a device; e.g., 
read a write-only device. 

20 ENOTDIR Not a directory 

A non-directory was specified where a directory is required, for example in a 
path prefix or as an argument to chdir(2). 

21 EISDIR Is a directory 

An attempt was made to write on a directory. 
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22 EINVAL Invalid argument 

Some invalid argument (e.g., dismounting a non-mounted device; mentioning 
an undefined signal in signal, or kill] Teading or writing a file for which Iseek 
has generated a negative pointer) was attempted. The math functions 
described in the (3M) entries of this manual causes the invalid argument to 
be set. 

23 ENFILE File table overflow 

The system file table is full, and temporarily no more opens can be accepted. 

24 EMFILE Too many open files 

No process may have more than 20 file descriptors open at a time. When a 
record loch is being created with fcnti, there are too many files with record 
lochs on them. 

25 ENOTTY Not a character device 

An attempt was made to ioctl{ 2) a file that is not a special character device. 

26 ETXTBSY Text file busy 

An attempt was made to execute a pure-procedure program that is currently 
open for writing. Also an attempt to open for writing a pure-procedure pro¬ 
gram that is being executed. 

27 EFBIG File too large 

The size of a file exceeded the maximum file size {1,082,201,088 bytes) or 
ULIMIT; see ulimit( 2). 

28 ENOSPC No space left on device 

During a write to an ordinary file, there is no free space left on the device. In 
fcnti, the setting or removing of record locks on a file cannot be accomplished 
because there are no more record entries left on the system. 

29 ESPIPE Illegal seek 

An Iseek was issued to a pipe. 

30 EROFS Read-only file system 

An attempt to modify a file or directory was made on a device mounted 
read-only. 

31 EMLINK Too many links 

An attempt to make more than the maximum numbeT of links (1000) to a file. 

32 EPIPE Broken pipe 

A write on a pipe for which there is no process to Tead the data. This condi¬ 
tion normally generates a signal; the error is returned if the signal is ignored. 

33 EDOM Math argument 

The argument of a function in the math package (3M) is out of the domain of 
the function. 

34 ERANGE Result too large 

The value of a function in the math package (3M) is not representable within 
machine precision. 

35 ENOMSG No message of desired type 

An attempt was made to receive a message of a type that does not exist on 
the specified message queue; see m$gop{ 2). 

36 EIDRM Identifier Removed 

This error is returned to processes that Tesume execution due to the removal 
of an identifier from the file system’s name space [see msgctl{ 2), semctl( 2), and 
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shmctl( 2)]. 


45 EDEADLK Deadlock 

A deadlock situation was detected and avoided. 


DEFINITIONS 
Process ID 

Each active process in the system is uniquely identified by a positive integer called a 
process ID. The range of this ID is from 1 to 30,000. 

Parent Process ID 

A new process is created by a currently active process; see fork( 2). The parent pro¬ 
cess ID of a process is the process ID of its creator. 

Process Group ID 

Each active process is a member of a process group that is identified by a positive 
integer called the process group ID. This ID is the process ID of the group leader. This 
grouping permits the signaling of related processes; see kill(2). 

Tty Group ID 

Each active process can be a member of a terminal group that is identified by a posi¬ 
tive integer called the tty group ID. This grouping is used to terminate a group of 
related processes upon termination of one of the processes in the group; see exit{ 2) 
and signal( 2). 

Real User ID and Real Group ID 

Each user allowed on the system is identified by a positive integer called a real user 
ID. 


Each user is also a member of a group. The group is identified by a positive integer 
called the real group ID. 

An active process has a real user ID and real group ID that are set to the real user ID 
and real group ID, respectively, of the user responsible for the creation of the process. 

Effective User ID and Effective Group ID 

An active process has an effective user ID and an effective group ID that are used to 
determine file access permissions (see below). The effective user ID and effective 
group ID are equal to the process’s real user ID and real group ID respectively, unless 
the process or one of its ancestors evolved from a file that had the set-user-ID bit or 
set-group ID bit set; see exec( 2). 

Super-user 

A process is recognized as a super-user process and is granted special privileges if its 
effective user ID is 0. 
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Special Processes 

The processes with a process ID of 0 and a process ID of 1 are special processes and 
are referred to as procO and prod. 

ProcO is the scheduler. Prod is the initialization process ( init ). Procl is the ances¬ 
tor of every other process in the system and is used to control the process structure. 

File Descriptor 

A file descriptor is a small integer used to do I/O on a file. The value of a file 
descriptor is from 0 to 19. A process may have no more than 20 file descriptors (0- 
19) open simultaneously. A file descriptor is returned by system calls such as 
open(2), or pipe{ 2). The file descriptor is used as an argument by calls such as 
read( 2), write{2), ioctl( 2), and close{ 2). 


File Name 

Names consisting of 1 to 14 characters may be used to name an ordinary file, special 
file, or directory. 

These characters may be selected from the set of all character values excluding \0 
(null) and the ASCII code for / (slash). 

Note that it is generally unwise to use *, T, [, or ] as part of file names because of the 
special meaning attached to these characters by the shell. See sh( 1). Although per¬ 
mitted, it is advisable to avoid the use of unprintable characters in file names. 

Path Name and Path Prefix 

A path name is a null-terminated character string starting with an optional slash 
(/), followed by zero or more directory names separated by slashes; optionally fol¬ 
lowed by a file name. 

More precisely, a path name is a null-terminated character string constructed as fol¬ 
lows: 


<path-name>::=<file-name>|<path-prefix><file-name>[/ 

<path-prefix>::=<rtprefix>|/<rtprefix> 

<rtprefix>::=<dirname>/|<rtprefix><dirname>/ 


where <file-name> is a string of 1 to 14 characters other than the ASCII slash and 
null, and <dirname> is a string of 1 to 14 characters (other than the ASCII slash and 
null) that names a directory. 


If a path name begins with a slash, the path search begins at the root directory. 
Otherwise, the search begins from the current working directory. 

A slash by itself names the root directory. 
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Unless specifically stated otherwise, the null path name is treated as if it named a 
non-existent file. 

Directory 

Directory entries are called links. By convention, a directory contains at least two 
links, . and referred to as dot and dot-dot respectively. Dot refers to the directory 
itself and dot-dot refers to its parent directory. 

Root Directory and Current Working Directory 

Each process has associated with it a concept of a root directory and a current 
working directory for the purpose of resolving path name searches. The root direc¬ 
tory of a process need not be the root directory of the root file system. 

File Access Permissions 

Read, write, and execute/search permissions on a file are granted to a process if one 
or more of the following are true: 

The effective user ID of the process is super-user. 

The effective user ID of the process matches the user ID of the owner of the file 
and the appropriate access bit of the “owner” portion (0700) of the file mode 
is set. 

The effective user ID of the process does not match the user ID of the owner of 
the file, and the effective group ID of the process matches the group of the file 
and the appropriate access bit of the “group” portion (070) of the file mode is 
set. 

The effective user ID of the process does not match the user ID of the owner of 
the file, and the effective group ID of the process does not match the group ID 
of the file, and the appropriate access bit of the “other” portion (07) of the 
file mode is set. 

Otherwise, the corresponding permissions are denied. 


Message Queue Identifier 

A message queue identifier (msqid) is a unique positive integer created by a msgget( 2) 
system call. Each msqid has a message queue and a data structure associated with 


it. The data 
members: 

structure is referred 

to as msqid^ds and contains the following 

struct 

ipc_perm msg_perm; 

/* operation permission struct */ 

ushort 

msg_qnum; 

/* number of msgs on q */ 

ushort 

msg_qbytes; 

/* max number of bytes on q */ 

ushort 

msgjspid; 

/* pid of last msgsnd operation */ 

ushort 

msgjrpid; 

/* pid of last msgrcv operation */ 

time_t 

msg_stime; 

/* last msgsnd time */ 

time_t 

msg_rtime; 

/* last msgrcv time */ 

time_t 

msg_ctime; 

/* last change time */ 

/* Times measured in secs since */ 
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/* 00:00:00 GMT, Jan. 1, 1970 */ 


Msg_perm is an ipc_perm structure that specifies the message operation permission 
(see below). This structure includes the following members: 


ushort 

cuid; 

/* creator user id */ 

ushort 

cgid; 

/* creator group id */ 

ushort 

uid; 

/* user id */ 

ushort 

gid; 

/* group id */ 

ushort 

mode; 

/* r/w permission */ 


Msg_qnum is the number of messages currently on the queue. Msg_qbyt.es is the 
maximum number of bytes allowed on the queue. Msg_lspid is the process id of the 
last process that performed a msgsnd operation. Msg_lrpid is the process id of the 
last process that performed a msgrcv operation. Msg_stime is the time of the last 
msgsnd operation, msg_rtime is the time of the last msgrcv operation, and 
msg_ctime is the time of the last msgctl{ 2) operation that changed a member of the 
above structure. 

Message Operation Permissions 

In the msgop( 2) and msgctl{2) system call descriptions, the permission required for an 
operation is given as "{token}", where "token" is the type of permission needed inter¬ 
preted as follows: 


00400 

00200 

00060 

00006 


Read by user 
Write by user 
Read, Write by group 
Read, Write by others 


Read and Write permissions on a msqid are granted to a process if one or more of 
the following are true: 

The effective user ID of the process is super-user. 

The effective user ID of the process matches msg_perm.[c]uid in the data 
structure associated with msqid and the appropriate bit of the “user” portion 
(0600) of msg—perm.mode is set. 

The effective user ID of the process does not match msg_perm.[c]uid and the 
effective group ID of the process matches msg_perm.[c]gid and the appropri¬ 
ate bit of the “group” portion (060) of msg_perm.mode is set. 

The effective user ID of the process does not match msg_perm.[c]uid and the 
effective group ID of the process does not match msg_perm.(c]gid and the 
appropriate bit of the “other” portion (06) of msg_perm.mode is set. 


Otherwise, the corresponding permissions are denied. 
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Semaphore Identifier 

A semaphore identifier (semid) is a unique positive integer created by a semget( 2) 
system call. Each semid has a set of semaphores and a data structure associated 
with it. The data structure is referred to as semitLds and contains the following 
members: 


struct ipc_perm sem_perm; /* operation permission struct */ 

ushort sem_nsems; /* number of sems in set */ 

time_t sem_otime; /* last operation time */ 

time_t sem_ctime; /* last change time */ 

/* Times measured in secs since */ 
/* 00:00:00 GMT, Jan. 1, 1970 */ 


Sem_perm is an ipc_perm structure that specifies the semaphore operation permis¬ 
sion (see below). This structure includes the following members: 


ushort 

cuid; 

/* creator user id */ 

ushort 

cgid; 

/* creator group id */ 

ushort 

uid; 

/* user id */ 

ushort 

gid; 

/* group id */ 

ushort 

mode; 

/* r/a permission */ 

The value of 

sem_nsems 

is equal to the number of semaphores in the set. Each 


semaphore in the set is referenced by a positive integer referred to as a 8em_num. 
Sem_num values run sequentially from 0 to the value of sem_nsems minus 1. 
Sem_otime is the time of the last semop( 2) operation, and sem_ctime is the time 
of the last semctl( 2) operation that changed a member of the above structure. 


A semaphore is a data structure that contains the following members: 


ushort semval; 
short sempid; 
ushort semncnt; 
ushort semzcnt; 


/* semaphore value */ 

/* pid of last operation */ 

/* # awaiting semval > cval */ 
/* # awaiting semval = 0 */ 


Semval is a non-negative integer. Sempid is equal to the process ID of the last pro¬ 
cess that performed a semaphore operation on this semaphore. Semncnt is a count 
of the number of processes that are currently suspended awaiting this semaphore’s 
semval to become greater than its current value. Semzcnt is a count of the number 
of processes that are currently suspended awaiting this semaphore’s semval to 
become zero. 

Semaphore Operation Permissions 

In the semop( 2) and semctl( 2) system call descriptions, the permission required for an 
operation is given as "{token}", where "token" is the type of permission needed inter¬ 
preted as follows: 
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00400 

Read by user 

00200 

Alter by user 

00060 

Read, Alter by group 

00006 

Read, Alter by others 


Read and Alter permissions on a semid are granted to a process if one or more of the 
following are true: 

The effective user ID of the process is super-user. 

The effective user ID of the process matches sem_perm.[c]uid in the data 
structure associated with semid and the appropriate bit of the “user” portion 
( 0600 ) of sem_perm.mode is set. 

The effective user ID of the process does not match sem_perm.[e]uid and the 
effective group ID of the process matches sem_perm.[c]gid and the appropri¬ 
ate bit of the “group” portion (060) of sem_perm.mode is set. 

The effective user ID of the process does not match sem_perm.[c]uid and the 
effective group ID of the process does not match sem_perm.[c]gid and the 
appropriate bit of the “other” portion ( 06 ) of sem_perm.mode is set. 

Otherwise, the corresponding permissions are denied. 

Shared Memory Identifier 

A shared memory identifier (shmid) is a unique positive integer created by a 
shmget{ 2) system call. Each shmid has a segment of memory (referred to as a shared 
memory segment) and a data structure associated with it. The data structure is 
referred to as shmid_ds and contains the following members: 


struct 

ipc_perm shm_perm; 

int 

shm_segsz; 

ushort 

shm_cpid; 

ushort 

shmjpid; 

short 

shm_nattch; 

time_t 

shm_atime; 

time_t 

shm_dtime; 

time_t 

shm_ctime; 


/* operation permission struct */ 
/* size of segment */ 

/* creator pid */ 

l* pid of last operation */ 

/* number of current attaches */ 
/* last attach time */ 

/* last detach time */ 

/* last change time */ 

/* Times measured in secs since */ 
/* 00:00:00 GMT, Jan. 1. 1970 */ 


Shm_perm is an ipc_perm structure that specifies the shared memory operation 
permission (see below). This structure includes the following members: 


ushort cuid; 
ushort cgid; 
ushort uid; 
ushort gid; 
ushort mode; 


/* creator user id */ 
/* creator group id */ 
/* user id */ 

/* group id */ 

/* r/w permission */ 
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Shm_»egsz specifies the size of the shared memory segment. Shm_cpid is the pro¬ 
cess id of the process that created the shared memory identifier. Shm_lpid is the 
process id of the last process that performed a ahmop( 2) operation. Shm_nattch is 
the number of processes that currently have this segment attached. Shxn_atixne is 
the time of the last shmat operation, shm_dtime is the time of the last shmdt 
operation, and shm_ctime is the time of the last shmctl( 2) operation that changed 
one of the members of the above structure. 


Shared Memory Operation Permissions 

In the shmop( 2) and shmctl(2) system call descriptions, the permission required for an 
operation is given as "{token}", where "token" is the type of permission needed inter¬ 
preted as follows: 

00400 Read by user 

00200 Write by user 

00060 Read, Write by group 

00006 Read, Write by others 


Read and Write permissions on a shmid are granted to a process if one or more of 
the following are true: 

The effective user ID of the process is super-user. 

The effective user ID of the process matches shm_perm.[c]uid in the data 
structure associated with shmid and the appropriate bit of the “user” portion 
( 0600 ) of shm_perm.mode is set. 

The effective user ID of the process does not match shm_perm.[c]uid and the 
effective group ID of the process matches shm_perm.[c]gid and the appropri¬ 
ate bit of the “group” portion (060) of shm_perm.mode is set. 

The effective user ID of the process does not match shm_perm.[c]uid and the 
effective group ID of the process does not match shm_perm.[c]gid and the 
appropriate bit of the “other” portion (06) of shm_perm.mode is set. 

Otherwise, the corresponding permissions are denied. 


SEE ALSO 

close(2), ioctl(2), open(2), pipe(2), read(2), write(2), intro(3). 
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NAME 

access — determine accessibility of a file 


SYNOPSIS 

int access (path, amode) 
char *path; 
int amode; 


DESCRIPTION 

Path points to a path name naming a file. Access checks the named file for accessi¬ 
bility according to the bit pattern contained in amode , using the real user ID in place 
of the effective user ID and the real group ID in place of the effective group ID. The bit 
pattern contained in amode is constructed as follows: 

04 read 

02 write 

01 execute (search) 

00 check existence of file 


Access to the file is denied if one or more of the following are true: 

ENOTDIR] A component of the path prefix is not a directory. 
ENOENT] Read, write, or execute (search) permission is 
requested for a null path name. 

ENOENT] The named file does not exist. 

[EACCES] Search permission is denied on a component of the 
path prefix. 

[EROFS] Write access is requested for a file on a read-only 
file system. 

[ETXTBSY] Write access is requested for a pure procedure 
(shared text) file that is being executed. 

[EACCESS] Permission bits of the file mode do not permit 
the requested access. 

[EFAULT] Path points outside the allocated address 
space for the process. 


The owner of a file has permission checked with respect to the “owner” read, write, 
and execute mode bits Members of the file’s group other than the owner have permis¬ 
sions checked with respect to the “group” mode bits, and all others have permissions 
checked with respect to the “other” mode bits. 


RETURN VALUE 
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If the requested access is permitted, a value of 0 is returned. Otherwise, a value of 
—1 is returned and errno is set to indicate the error. 


SEE ALSO 

chmod(2), stat(2). 
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NAME 

acct — enable or disable process accounting 


SYNOPSIS 

int acct (path) 
char *path; 


DESCRIPTION 

Acct is used to enable or disable the system process accounting routine. If the rou¬ 
tine is enabled, an accounting record will be written on an accounting file for each 
process that terminates. Termination can be caused by one of two things: an exit 
call or a signal; see exit{ 2) and signal(2). The effective user ID of the calling process 
must be super-user to use this call. 

Path points to a path name naming the accounting file. The accounting file format 
is given in accf(4). 


The accounting routine is enabled if path is non-zero and no errors occur during the 
system call. It is disabled if path is zero and no errors occur during the system call. 


Acct will fail if one or more of the following are true: 


(EPERMj 

[EBUSY] 

[ENOTDIR] 

[ENOENT] 


The effective user of the calling process is not super-user. 

An attempt is being made to enable accounting when it is already 
enabled. 

A component of the path prefix is not a directory. 

One or more components of the accounting file path name do not 
exist. 


[EACCES] 

[EACCES] 

[EACCES] 

[EISDIR] 

[EROFS] 

[EFAULT] 


A component of the path prefix denies search permission. 
The file named by path is not an ordinary file. 

Mode permission is denied for the named accounting file. 
The named file is a directory. 

The named file resides on a read-only file system. 

Path points to an illegal address. 


RETURN VALUE 

Upon successful completion, a value of 0 is returned. Otherwise, a value of —1 is 
returned and errno is set to indicate the error. 
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SEE ALSO 

exit(2), signal(2), acct(4). 
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NAME 

alarm — set a process alarm clock 


SYNOPSIS 

unsigned alarm (sec) 
unsigned sec; 


DESCRIPTION 

Alarm instructs the alarm clock of the calling process to send the signal SIGALRM to 
the calling process after the number of real time seconds specified by sec have 
elapsed; see signal(2). 

Alarm requests are not stacked; successive calls reset the alarm clock of the calling 
process. 

If sec is 0, any previously made alarm request is canceled. 


RETURN VALUE 

Alarm returns the amount of time previously remaining in the alarm clock of the 
calling process. 


SEE ALSO 

pause(2), signal(2). 
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NAME 


brk, sbrk — change data segment space allocation 


SYNOPSIS 

ini brk (endds) 
char *endds; 

char *sbrk (incr) 
int incr; 


DESCRIPTION 

Brk and sbrk are used to change dynamically the amount of space allocated for the 
calling process’s data segment; see exec(2). The change is made by resetting the 
process’s break value and allocating the appropriate amount of space. The break 
value is the address of the first location beyond the end of the data segment. The 
amount of allocated space increases as the break value increases. The newly allo¬ 
cated space is set to zero. 

Brk sets the break value to endds and changes the allocated space accordingly. 

Sbrk adds incr bytes to the break value and changes the allocated space accordingly. 
Incr can be negative, in which case the amount of allocated space is decreased. 


Brk and sbrk will fail without making any change in the allocated space if one or 
more of the following are true: 

Such a change would result in more space being allocated than is allow-ed by 
a system-imposed maximum (see ulimit(2)). [ENOMEM] 

Such a change would result in the break value being greater than or equal to 
the start address of any attached shared memory segment (see shmop{ 2)). 


RETURN VALUE 

Upon successful completion, brk returns a value of 0 and sbrk returns the old break 
value. Otherwise, a value of —1 is returned and errno is set to indicate the error. 


SEE ALSO 

exec(2), shmop(2), ulimit(2). 


( 
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NAME 

chdir — change working directory 


SYNOPSIS 

int chdir (path) 
char *path; 

DESCRIPTION 

Path points to the path name of a directory. Chdir causes the named directory to 
become the current working directory, the starting point for path searches for path 
names not beginning with /. 


Chdir will fail and the current working directory will be unchanged if one or more of 
the following are true: 


(ENOTD1R) 

JENOENT] 

[EACCES] 

[EFAULT] 


A component of the path name is not a directory. 

The named directory does not exist. 

Search permission is denied for any component of the path name. 
Path points outside the allocated address space of the process. 


RETURN VALUE 

Upon successful completion, a value of 0 is returned. Otherwise, a value of —1 is 
returned and errno is set to indicate the error. 


SEE ALSO 

chroot(2). 


Icon International, Inc. 


1 



CHMOD (2) 


SYSTEM CALLS 


CHMOD (2) 


NAME 

chmod — change mode of file 


SYNOPSIS 

int chmod (path, mode) 
char *path; 
int mode; 


DESCRIPTION 

Path points to a path name naming a file. Chmod sets the access permission portion 
of the named file’s mode according to the bit pattern contained in mode. 


Access permission bits are interpreted as follows: 


04000 

02000 

01000 

00400 

00200 

00100 

00070 

00007 


Set user ID on execution. 

Set group ID on execution. 

Save text image after execution. 

Read by owner. 

Write by owner. 

Execute (search if a directory) by owner. 
Read, write, execute (search) by group. 
Read, write, execute (search) by others. 


The effective user ID of the process must match the owner of the file or be super-user 
to change the mode of a file. 


If the effective user ID of the process is not super-user, mode bit 01000 (save text 
image on execution) is cleared. 

If the effective user ID of the process is not super-user and the effective group ID of 
the process does not match the group ID of the file, mode bit 02000 (set group ID on 
execution) is cleared. 

If an executable file is prepared for sharing then mode bit 01000 prevents the system 
from abandoning the swap-space image of the program-text portion of the file when 
its last user terminates. Thus, when the next user of the file executes it, the text 
need not be read from the file system but can simply be swapped in, saving time. 

Chmod will fail and the file mode will be unchanged if one or more of the following 
are true: 

[ENOTD1R] A component of the path prefix is not a directory. 

[ENOENT] The named file does not exist. 
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[EACCES] Search permission is denied on a component of the path prefix. 

[EPERM] The effective user ID does not match the owner of the file and the 

effective user ID is not super-user. 

[EROFS] The named file resides on a read-only file system. 

[EFAULT] Path points outside the allocated address space of the process. 

RETURN VALUE 

Upon successful completion, a value of 0 is returned. Otherwise, a value of —1 is 
returned and errno is set to indicate the error. 


SEE ALSO 

chown(2), mknod(2). 
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SYSTEM CALLS 


CHOWN (2) 


NAME 

chown — change owner and group of a file 

SYNOPSIS 

int chown (path, owner, group) 

char *path; 

int owner, group; 

DESCRIPTION 

Path points to a path name naming a file. The owner ID and group ID of the named 
file are set to the numeric values contained in owner and group respectively. 

Only processes with effective user ID equal to the file owner or super-user may change 
the ownership of a file. 

If chown is invoked by other than the super-user, the set-user-ID and set-group-ID 
bits of the file mode, 04000 and 02000 respectively, will be cleared. 

Chown will fail and the owner and group of the named file will remain unchanged if 
one or more of the following are true: 

[ENOTDIR] A component of the path prefix is not a directory. 

[ENOENTj The named file does not exist. 

[EACCES] Search permission is denied on a component of the path prefix. 

[EPERM] The effective user ID does not match the owner of the file and the 

effective user ID is not super-user. 

jEROFS] The named file resides on a read-only file system. 

[EFAULT] Path points outside the allocated address space of the process. 

RETURN VALUE 

Upon successful completion, a value of 0 is returned. Otherwise, a value of —1 is 
returned and errno is set to indicate the error. 

SEE ALSO 

chmod(2). 

chown(l) in the ICON/UXV User Reference Manual. 
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NAME 

chroot — change root directory 


SYNOPSIS 

int chroot (path) 
char *path; 

DESCRIPTION 

Path points to a path name naming a directory. Chroot causes the named directory 
to become the root directory, the starting point for path searches for path names 
beginning with /. The user’s working directory is unaffected by the chroot system 
call. 


The effective user ID of the process must be super-user to change the root directory. 

The .. entry in the root directory is interpreted to mean the root directory itself. 
Thus, .. cannot be used to access files outside the subtree rooted at the root direc¬ 
tory. 


Chroot will fail and the root directory will remain unchanged if one or more of the 
following are true: 

(ENOTDIR] Any component of the path name is not a directory. 

[ENOENT] The named directory does not exist. 

[EPERM] The effective user ID is not super-user. 

[EFAULT] Path points outside the allocated address space of the process. 


RETURN VALUE 

Upon successful completion, a value of 0 is returned. Otherwise, a value of —1 is 
returned and errno is set to indicate the error. 


SEE ALSO 

chdir(2). 
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NAME 

close — close a file descriptor 


SYNOPSIS 

int close (fildes) 
int fildes; 


DESCRIPTION 

Fildes is a file descriptor obtained from a creat, open, dup, fcntl, or pipe system call. 
Close closes the file descriptor indicated by fildes. All outstanding record locks 
owned by the process (on the file indicated by fildes) are removed. 

[EBADF] Close will fail if fildes is not a valid open file clescriptor. 


RETURN VALUE 

Upon successful completion, a value of 0 is returned. Otherwise, a value of —1 is 
returned and errno is set to indicate the error. 


SEE ALSO 

creat(2), dup(2), exec(2), fcntl(2), open(2), pipe(2). 
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NAME 

creat — create a new file or rewrite an existing one 


SYNOPSIS 

int creat (path, mode) 
char *path; 
int mode; 


DESCRIPTION 

Creat creates a new ordinary file or prepares to rewrite an existing file named by the 
path name pointed to by path. 

If the file exists, the length is truncated to 0 and the mode and owner are unchanged. 
Otherwise, the file’s owner ID is set to the effective user ID, of the process the group 
ID of the process is set to the effective group ID, of the process and the low-order 12 
bits of the file mode are set to the value of mode modified as follows: 

All bits set in the process’s file mode creation mask are cleared. See 
umask( 2). 

The “save text image after execution bit” of the mode is cleared. See 
chmod(2). 

Upon successful completion, the file descriptor is returned and the file is open for 
writing, even if the mode does not permit writing. The file pointer is set to the 
beginning of the file. The file descriptor is set to remain open across exec system 
calls. See fcntl( 2). No process may have more than 20 files open simultaneously. A 
new file may be created with a mode that forbids writing. 


Creat will fail if one or more of the following are true: 

[ENOTDIR] A component of the path prefix is not a directory. 

[ENOENT] A component of the path prefix does not exist. 

(EACCES) Search permission is denied on a component of the path prefix. 

(ENOENT] The path name is null. 

(EACCES] The file does not exist and the directory in which the file is to be 

created does not permit writing. 

(EROFS] The named file resides or would reside on a read-only file system. 

[ETXTBSY] The file is a pure procedure (shared text) file that is being executed. 

(EACCES] The file exists and write permission is denied. 

(E1SDIR] The named file is an existing directory. 

[EMFILE] Twenty (20) file descriptors are currently open. 

[EFAULT] Path points outside the allocated address space of the process. 
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[ENFILE] The system file table is full. 

RETURN VALUE 

Upon successful completion, a non-negative integer, namely the file descriptor, is 
returned. Otherwise, a value of —1 is returned and errno is set to indicate the error. 

SEE ALSO 

chmod(2), close(2), dup(2), fcntl(2), keek(2), open(2), read(2), umask(2), write(2). 
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NAME 

dup — duplicate an open file descriptor 


SYNOPSIS 

int dup (fildes) 
int fildes; 


DESCRIPTION 

Fildes is a file descriptor obtained from a creat, open, dup, fcntl, or pipe system call. 
Dup returns a new file descriptor having the following in common with the original: 

Same open file (or pipe). 

Same file pointer (i.e., both file descriptors share one file pointer). 

Same access mode (read, write or read/write). 

The new- file descriptor is set to remain open across exec system calls. See fcntl( 2). 

The file descriptor returned is the low’est one available. 

Dup will fail if one or more of the following are true: 

[EBADF] Fildes is not a valid open file descriptor. 

[EMFILE] Twenty (20) file descriptors are currently open. 

RETURN VALUE 

Upon successful completion a non-negative integer, namely the file descriptor, is 
returned. Otherwise, a value of —1 is returned and errno is set to indicate the error. 


SEE ALSO 

creat(2), close(2), exec(2), fcntl(2), open(2), pipe(2). 
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NAME 

execl, execv, execle, execve, execlp, execvp — execute a file 



SYNOPSIS 

int execl (path, argO, argl, argn, 0) 
char *path, *argO, *argl, *argn; 

int execv (path, argv) 
char *path, *argv[ ]; 

int execle (path, argO, argl, ..., argn, 0, envp) 
char *path, *argO, *argl, ..., *argn, *envp[ ]; 

int execve (path, argv, envp) 
char *path, *argv[ ], *envp[ ]; 

int execlp (file, argO, argl, ..., argn, 0) 
char *file, *argO, *argl, ..., *argn; 

int execvp (file, argv) 
char *file, *argv[]; 


DESCRIPTION 

Exec in all its forms transforms the calling process into a new process. The new pro¬ 
cess is constructed from an ordinary, executable file called the new process file. This 
file consists of a header (see a.out(4)), a text segment, and a data segment. The data 
segment contains an initialized portion and an uninitialized portion (bss). There can 
be no return from a successful exec because the calling process is overlaid by the new 
process. 

When a C program is executed, it is called as follows: 

main (argc, argv, envp) 
int argc; 

char **argv, **envp; 


where argc is the argument count and argv is an array of character pointers to the 
arguments themselves. As indicated, argc is conventionally at least one and the first 
member of the array points to a string containing the name of the file. 
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Path points to a path name that identifies the new process file. 

File points to the new process file. The path prefix for this file is obtained by a 
search of the directories passed as the environment line "PATH =" (see environ( 5)). 
The environment is supplied by the shell (see sh( 1)). 

ArgO, argl, ..., argn are pointers to null-terminated character strings. These strings 
constitute the argument list available to the new process. By convention, at least 
argO must be present and point to a string that is the same as path (or its last com¬ 
ponent). 


Argv is an array of character pointers to null-terminated strings. These strings con¬ 
stitute the argument list available to the new process. By convention, argv must 
have at least one member, and it must point to a string that is the same as path (or 
its last component). Argv is terminated by a null pointer. 

Envp is an array of character pointers to null-terminated strings. These strings con¬ 
stitute the environment for the new process. Envp is terminated by a null pointer. 
For execl and execv, the C run-time start-off routine places a pointer to the environ¬ 
ment of the calling process in the global cell: 

extern char **environ; 

and it is used to pass the environment of the calling process to the new process. 

File descriptors open in the calling process remain open in the new process, except 
for those whose close-on-exec flag is set; see fcntl( 2). For those file descriptors that 
remain open, the file pointer is unchanged. 

Signals set to terminate the calling process will be set to terminate the new process. 
Signals set to be ignored by the calling process will be set to be ignored by the new 
process. Signals set to be caught by the calling process will be set to terminate new 
process; see signal(2). 

If the set-user-ID mode bit of the new process file is set (see chmod{ 2)), exec sets the 
effective user ID of the new process to the owner ID of the new process file. Similarly, 
if the set-group-ID mode bit of the new process file is set, the effective group ID of the 
new process is set to the group ID of the new process file. The real user ID and real 
group ID of the new process remain the same as those of the calling process. 

The shared memory segments attached to the calling process will not be attached to 
the new process (see shmop( 2)). 

Profiling is disabled for the new process; see profil( 2). 

The new' process also inherits the following attributes from the calling process: 


nice value (see m'ce(2)) 
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process ID 

parent process ID 

process group ID 

semadj values (see «emop(2)) 

tty group ID (see exjf(2) and signal(2)) 

trace flag (see ptrace( 2) request 0) 

time left until an alarm clock signal (see atarm{ 2)) 

current working directory 

root directory 

file mode creation mask (see umask(2)) 

file size limit (see vlimit( 2)) 

utime, stime, cutime, and cstime (see times(2)) 


Exec will fail and return to tbe calling process if one ot more of the following are 
true: 


[ENOENT] 

[ENOTDIR] 

(EACCES] 

[EACCES] 

[EACCES] 

[ENOEXEC] 

[ETXTBSY] 

[ENOMEM] 

IE2BIG] 

[EFAULT] 

[EFAULT] 


One or more components of the new process path name of the file 
do not exist. 

A component of the new process path of the file prefix is not a 
directory. 

Search permission is denied for a director)’ listed in the new process 
file’s path prefix. 

The new process file is not an ordinary file. 

The new process file mode denies execution permission. 

The exec is not an txtclp or execvp, and the new process file has the 
appropriate access permission but an invalid magic number in its 
header. 

The new process file is a pure procedure (shared text) file that is 
currently open foT writing by some process. 

The new process requires more memory than is allowed by the 
system-imposed maximum MAXMEM 

The number of bytes in the new process’s argument list is greater 
than the system-imposed limit of 5120 bytes. 

The new process file is not as long as indicated by the size values in 
its header. 

Path, argv, or envp point to an illegal address. 
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RETURN VALUE 

If exec returns to the calling process an error has occurred; the return value will be 
—1 and errno will be set to indicate the error. 


SEE ALSO 

alarm(2), exit(2), fork(2), nice(2), ptrace(2), semop(2), signal(2), times(2), ulifnit(2), 

umask(2), a.out(4), environ(5). 

sh(l) in the ICON/UX User Reference Manual. 
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NAME 

exit, _exit — terminate process 


SYNOPSIS 

void exit (status) 
int status; 
void _exit (status) 
int status; 


DESCRIPTION 

Exit terminates the calling process with the following consequences: 

All of the file descriptors open in the calling process are closed. 

If the parent process of the calling process is executing a wait, it is notified of 
the calling process’s termination and the low order eight bits (i.e., bits 0377) 
of status are made available to it; see wait{2). 

If the parent process of the calling process is not executing a wait, the calling 
process is transformed into a zombie process. A zombie process is a process 
that only occupies a slot in the process table. It has no other space allocated 
either in user or kernel space. The process table slot that it occupies is par¬ 
tially overlaid with time accounting information (see <sys/proc.h>) to be 
used by times. 

The parent process ID of all of the calling process’s existing child processes 
and zombie processes is set to 1. This means the initialization process [see 
intro{ 2)] inherits each of these processes. 

Each attached shared memory segment is detached and the value of 
shm_nattach in the data structure associated with its shared memory 
identifier is decremented by 1. 

For each semaphore for which the calling process has set a semadj value [see 
semop( 2)], that semadj value is added to the semval of the specified sema¬ 
phore. 

If the process has a process, text, or data lock, an unlock is performed (see 
plock( 2)). 

An accounting record is written on the accounting file if the system’s 
accounting routine is enabled; see acct{ 2). 

If the process ID, tty group ID, and process group ID of the calling process are 
equal, the SIGHUP signal is sent to each process that has a process group ID 
equal to that of the calling process. 

The C function exit may cause cleanup actions before the process exits. The func¬ 
tion _exit circumvents all cleanup. 
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SEE ALSO 

acct(2), intro(2), plock(2), semop(2), signal(2), wait(2). 


WARNING 

See WARNING in signal( 2). 
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NAME 

fcntl — file control 


SYNOPSIS 

#include <fcntl.h> 

int fcntl (fildes, cmd, arg) 
int fildes, cmd, arg; 


DESCRIPTION 

Fcntl provides for control over open files. Fildes is an open file descriptor obtained 
from a creat, open, dup, fcntl, or pipe system call. 


The commands available are: 


FJDUPFD 


F.GETFD 


FjSETFD 

F_GETFL 

F_SETFL 

F.GETLK 


FJSETLK 


Return a new file descriptor as follows: 

Lowest numbered available file descriptor greater than or equal to 
arg. 

Same open file (or pipe) as the original file. 

Same file pointer as the original file (i.e., both file descriptors share 
one file pointer). 

Same access mode (read, write, or read/write). 

Same file status flags (i.e., both file descriptors share the same file 
status flags). 

The close-on-exec flag associated with the new file descriptor is set to 
remain open across eiec(2) system calls. 

Get the close-on-exec flag associated with the file descriptor fildes. If 
the low-order bit is 0 the file will remain open across exec, otherwise 
the file will be closed upon execution of exec. 

Set the close-on-exec flag associated with fildes to the low-order bit of 
arg (0 or 1 as above). 

Get file status flags. 

Set file status flags to arg. Only certain flags can be set; see fcntl( 5). 

Get the first lock which blocks the lock description given by the vari¬ 
able of type struct flock pointed to by arg. The information retrieved 
overwrites the information passed to fcntl in the flock structure. If no 
lock is found that would prevent this lock from being created, then 
the structure is passed back unchanged except for the lock type which 
will be set to F.UNLCK 

Set or clear a file segment lock according to the variable of type struct 
flock pointed to by arg [see fcnt1[ 5)]. The cmd F_SETLK is used to 
establish read (F_RDLCK) and write (F_\VRLCK) locks, as well as 
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remove either type of lock (F_UNLCK). If a read or write lock cannot 
be set, fcntl will return immediately with an error value of —1. 

FJSETLKW This cmd is the same as FJSETLK except that if a read or write lock is 
blocked by other locks, the process will sleep until the segment is free 
to be locked. 

A read lock prevents any process from write locking the protected area. More than 
one read lock may exist for a given segment of a file at a given time. The file 
descriptor on which a read lock is being placed must have been opened with read 
access. 

A write lock prevents any process from read locking or write locking the protected 
area. Only one write lock may exist for a given segment of a file at a given time. 
The file descriptor on which a write lock is being placed must have been opened with 
write access. 


The structure flock describes the type ( Ijtypc ), starting offset (Lwhence), relative 
offset (l^start), size (/_ ten), and process id (i_pieQ of the segment of the file to be 
affected. The process id field is only used with the F.GETLK cmd to return the value 
for a block in lock. Locks may start and extend beyond the current end of a file, but 
may not be negative relative to the beginning of the file. A lock may be set to 
always extend to the end of file by setting /_ len to zero (0). If such a lock also has 
/_start set to zero (0), the whole file will be locked. Changing or unlocking a segment 
from the middle of a larger locked segment leaves two smaller segments for either 
end. Locking a segment that is already locked by the calling process causes the old 
lock type to be removed and the new lock type to take affect. All locks associated 
with a file for a given process are removed when a file descriptor for that file is 
closed by that process or the process holding that file descriptor terminates. Locks 
are not inherited by a child process in a fork{ 2) system call. 

Fcntl will fail if one or more of the following are true: 


[EBADF] 

[EMFILE] 

[EINFILE] 

(EINVAL] 

|EACCESS] 


[EMFILE] 


[ENOSPC] 


Fildes is not a valid open file descriptor. 

Cmd isF_DUPFD and 20 file descriptors are currently open. 

Cmd is F_DUPFD and arg is negative or greater than 20. 

Cmd is F.GETLK, FJSETLK, or SETLKVV and arg or the data it points 
to is not valid. 

Cmd is FJSETLK the type of lock (Ltype) is a read (F_RDLCK) or 
write (F_WRLCK) lock and the segment of a file to be locked is 
already write locked by another process or the type is a write lock 
and the segment of a file to be locked is already read or write 
locked by another process. 

Cmd is F_SETLK or FJSETLKW, the type of lock is a read or write 
lock and there are no more file locking headers available (too many 
files have segments locked). 

Cmd is FJSETLK or F_SETLKW, the type of lock is a read or write 
lock and there are no more file locking headers available (too many 
files have segments locked) or there are no more record locks 
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JEDEADLK] 



available (too many file segments locked). 


Cmd is FJ5ETLK, when the lock is blocked by some lock from 
another process and sleeping (waiting) for that lock to become free, 
this causes a deadlock situation. 


RETURN VALUE 

Upon successful completion, the value returned depends on cmd as follows: 
FJDUPFD A new file descriptor. 

F.GETFD Value of flag (only the low-order bit is defined). 
FJSETFD Value other than —1. 

F_GETFL Value of file flags. 

F_SETFL Value other than —1. 

F.GETLK Value other that -1. 

FJSETLK Value other than —1. 

FJSETLKW Value other than -1. 


Otherwise, a value of —1 is returned and errno is set to indicate the error. 


SEE ALSO 

close(2), exec(2), open(2), fcntl(5). 
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NAME 

fork — create a new process 

SYNOPSIS 

int fork () 

DESCRIPTION 

Fork causes creation of a new process. The new process (child process) is an exact 
copy of the calling process (parent process). This means the child process inherits 
the following attributes from the parent process: 

environment 

close-on-exec flag (see exec( 2)) 

signal handling settings (i.e., SIG_DFL, SIG_ING, function address) 

set-user-E) mode bit 

set-group-ED mode bit 

profiling on/off status 

nice value (see nice{ 2)) 

all attached shared memory segments (see shmop( 2)) 
process group ID 

tty group ID (see exil( 2) and signal( 2)) 

trace flag (see ptrace( 2) request 0) 

time left until an alarm clock signal (see alarm( 2)) 

current working directory 

root directory 

file mode creation mask (see umask( 2)) 
file size limit (see ulimit(2)) 
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The child process differs from the parent process in the following ways: 

The child process has a unique process ID. 

The child process has a different parent process ID (i.e., the process ID of the 
parent process). 

The child process has its own copy of the parent’s file descriptors. Each of 
the child’s file descriptors shares a common file pointer with the correspond¬ 
ing file descriptor of the parent. 

All semadj values are cleared (see semop(2)). 

Process locks, text locks and data locks are not inherited by the child (see 
plock( 2)). 

The child process’s utime, stime, cutime, and cstime are set to 0. The time 
left until an alarm clock signal is reset to 0. 

Fork will fail and no child process will be created if one or more of the following are 
true: 

[EAGAIN] The system-imposed limit on the total number of processes under 

execution would be exceeded. 

[EAGAIN] The system-imposed limit on the total number of processes under 

execution by a single user would be exceeded. 


ry 

i i 
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RETURN VALUE 

Upon successful completion, fork returns a value of 0 to the child process and returns 
the process ID of the child process to the parent process. Otherwise, a value of —1 is 
returned to the parent process, no child process is created, and errno is set to indi¬ 
cate the error. 


SEE ALSO 

exec(2), nice(2), plock(2), ptrace(2), semop(2), shmop(2), signal(2), times(2), ulimit(2), 
umask(2), wait(2). 
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NAME 

getpid, getpgrp, getppid — get process, process group, and parent process IDs 

SYNOPSIS 

int getpid () 

int getpgrp ( ) 

int getppid ( ) 

DESCRIPTION 

Getpid returns the process ID of the calling process. 

Getpgrp returns the process group ID of the calling process. 

Getppid returns the parent process ID of the calling process. 

SEE ALSO 

exeo(2), fork(2), intro(2), setpgrp(2), signal(2). 
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NAME 

getuid, geteuid, getgid, getegid — get real user, effective user, real group, and 
effective group IDs 

SYNOPSIS 

unsigned short getuid ( ) 
unsigned short geteuid () 
unsigned short getgid ( ) 
unsigned short getegid () 

DESCRIPTION 

Getuid returns the real user ID of the calling process. 

Geteuid returns the effective user ID of the calling process. 

Getgid returns the real group ID of the calling process. 

Getegid returns the effective group ID of the calling process. 

SEE ALSO 

intro(2), setuid(2). 
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NAME 

ioctl — control device 


SYNOPSIS 

ioctl (fildes, request, arg) 
int fildes, request; 


DESCRIPTION 

Ioctl performs a variety of functions on character special files (devices). The write¬ 
ups of various devices in Section 7 of the ICON/UXV Administrator Reference Manual 
discuss how ioctl applies to them. 


Ioctl will fail if one or more of the following are true: 

[EBADF] Fildes is not a valid open file descriptor. 

[ENOTTY] Fildes is not associated with a character special device. 

[EINVAL] Request or arg is not valid. See Section 7 of the ICON/UXV 

Administrator Reference Manual. 

[EINTR] A signal was caught during the ioctl system call. 


RETURN VALUE 

If an error has occurred, a value of —1 is returned and errno is set to indicate the 
error. 


SEE ALSO 

termio(7) in the ICON/UX Administrator Reference Manual. 


/■ 
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NAME 

kill — send a signal to a process or a group of processes 


SYNOPSIS 

int kill (pid, sig) 
int pid, sig; 


DESCRIPTION 

Kill sends a signal to a process or a group of processes. The process or group of 
processes to which the signal is to be sent is specified by pid. The signal that is to be 
sent is specified by sig and is either one from the list given in signal(2), or 0. If sig is 
0 (the null signal), error checking is performed but no signal is actually sent. This 
can be used to check the validity of pid. 

The real or effective user ID of the sending process must match the real or effective 
user ID of the receiving process, unless the effective user ID of the sending process is 
super-user. 

The processes with a process ID of 0 and a process ID of 1 are special processes (see 
intro{2)) and will be referred to below as procO and prod, respectively. 

If pid is greater than zero, sig will be sent to the process whose process ID is equal to 
pid. Pid may equal 1. 

If pid is 0, sig will be sent to all processes excluding procO and prod whose process 
group ID is equal to the process group ID of the sender. 

If pid is —1 and the effective user ID of the sender is not super-user, sig will be sent to 
all processes excluding procO and prod whose real user ID is equal to the effective 
user ID of the sender. 

If pid is —1 and the effective user ID of the sender is super-user, sig will be sent to all 
processes excluding procO and prod. 

If pid is negative but not —1, sig will be sent to all processes whose process group ID 
is equal to the absolute value of pid. 


Kill will fail and no signal will be sent if one or more of the following are true: 
[EINVAL] Sig is not a valid signal number. 

[EINVAL] Sig is SIGKILL and pid is 1 (prod). 

[ESRCH] No process can be found corresponding to that specified by pid. 
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[EPERM] The user ID of the sending process is not super-user, and its real or 

effective user ID does not match the real or effective user ID of the 
receiving process. 


RETURN VALUE 

Upon successful completion, a value of 0 is returned. Otherwise, a value of —1 is 
returned and errno is set to indicate the error. 


SEE ALSO 

getpid(2), setpgrp(2), signal(2). 

kill(l) in the ICON/UX User Reference Manual. 
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NAME 

link — link to a file 


SYNOPSIS 

int link (pathl, path2) 
char *pathl, *path2; 


DESCRIPTION 


Pathl points to a path name naming an existing file. Path2 points to a path name 
naming the new directory entry to be created. Link creates a new link (directory 
entry) for the existing file. 


Link will fail and no link will be created if one or more of the following are true: 
[ENOTDIR] A component of either path prefix is not a directory. 

(ENOENT] A component of either path prefix does not exist. 

[EACCES] A component of either path prefix denies search permission. 

(ENOENT] The file named by pathl does not exist. 

[EEX3STJ The link named by path2 exists. 

[EPERM] The file named by pathl is a directory and the effective user ID is 

not super-user. 


[EXDEV] 

[ENOENT] 

[EACCES] 

[EROFS] 

[EFAULT] 

[EMLINK] 


The link named by paths and the file named by pathl are on 
different logical devices (file systems). 

Path2 points to a null path name. 

The requested link requires writing in a directory with a mode that 
denies write permission. 

The requested link requires writing in a directory on a read-only file 
system. 

Path points outside the allocated address space of the process. 

The maximum number of links to a file would be exceeded. 


RETURN VALUE 

Upon successful completion, a value of 0 is returned. Otherwise, a value of —1 is 
returned and errno is set to indicate the error. 


SEE ALSO 

unlink(2). 
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NAME 

lseek — move read/write file pointer 


SYNOPSIS 

long lseek (fildes, offset, whence) 
int fildes; 
long offset; 
int whence; 


DESCRIPTION 

Fildes is a file descriptor returned from a creat, open, dup, or fcntl system call. 
Lseek sets the file pointer associated with fildes as follows: 

If whence is 0, the pointer is set to offset bytes. 

If whence is 1, the pointer is set to its current location plus offset. 

If whence is 2, the pointer is set to the size of the file plus offset. 


Upon successful completion, the resulting pointer location, as measured in bytes from 
the beginning of the file, is returned. 


Lseek will fail and the file pointer will remain unchanged if one or more of the fol¬ 
lowing are true: 

[EBADF] Fildes is not an open file descriptor. 

[ESPIPE] Fildes is associated with a pipe or fifo. 

[EINVAL and SIGSYS signal] 

Whence is not 0, 1, or 2. 

(EINVAL] The resulting file pointer would be negative. 

Some devices are incapable of seeking. The value of the file pointer associated with 
such a device is undefined. 


RETURN VALUE 

Upon successful completion, a non-negative integer indicating the file pointer value is 
returned. Otherwise, a value of —1 is returned and errno is set to indicate the error. 


SEE ALSO 

creat(2), dup(2), fcntl(2), open(2). 
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NAME 

mknod — make a directory, or a special or ordinary file 


SYNOPSIS 

int mknod (path, mode, dev) 
char *path; 
int mode, dev; 


DESCRIPTION 

Mknod creates a new file named by the path name pointed to by path. The mode of 
the new file is initialized from mode. Where the value of mode is interpreted as fol¬ 
lows: 


0170000 file type; one of the following: 

0010000 fifo special 
0020000 character special 
0040000 directory 
0060000 block special 
0100000 or 0000000 ordinary file 
0004000 set user ID on execution 
0002000 set group ID on execution 
0001000 save text image after execution 
0000777 access permissions; constructed from the following 
0000400 read by owner 
0000200 write by owner 

0000100 execute (search on directory) by owner 
0000070 read, write, execute (search) by group 
0000007 read, write, execute (search) by others 


The owner ID of the file is set to the effective user ID of the process. The group ID of 
the file is set to the effective group ID of the process. 

Values of mode other than those above are undefined and should not be used. The 
low-order 9 bits of mode are modified by the process’s file mode creation mask: all 
bits set in the process’s file mode creation mask are cleared. See umask( 2). If mode 
indicates a block or character special file, dev is a configuration-dependent 
specification of a character or block I/O device. If mode does not indicate a block 
special or character special device, dev is ignored. 


Mknod may be invoked only by the super-user for file types other than FIFO special. 

Mknod will fail and the new file will not be created if one or more of the following 
are true: 

[EPERM] The effective user ID of the process is not super-user. 
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[ENOTDIR] 

(ENOENT) 

[EROFS] 

(EEX1STJ 

[EFAULT] 


A component of the path prefix is not a directory. 

A component of the path prefix does not exist. 

The directory in which the file is to be created is located on a read¬ 
only file system. 

The named file exists. 

Path points outside the allocated address space of the process. 


RETURN VALUE 

Upon successful completion a value of 0 is returned. Otherwise, a value of —1 is 
returned and errno is set to indicate the error. 


SEE ALSO 

chmod(2), exec(2), umask(2), fs(4). 

mkdir(l) in the 1CON/UX User Reference Manual. 
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NAME 

mount — mount a file system 

SYNOPSIS 

int mount (spec, dir, rwflag) 
char *spec, *dir; 
int rwflag; 


DESCRIPTION 

Mount requests that a removable file system contained on the block special file 

identified by spec be mounted on the directory identified by dir. Spec and dir are 

pointers to path names. 

Upon successful completion, references to the file dir will refer to the root directory 
on the mounted file system. 

The low-order bit of rwflag is used to control write permission on the mounted file 
system; if 1, writing is forbidden, otherwise writing is permitted according to indivi¬ 
dual file accessibility. 

Mount may be invoked only by the super-user. 

Mount will fail if one or more of the following are true: 

[EPERM] The effective user ID is not super-user. 

[ENOENT] Any of the named files does not exist. 

[ENOTDIR) A component of a path prefix is not a directory. 

[ENOTBLK] Spec is not a block special device. 

[ENXIO] The device associated with spec does not exist. 

[ENOTDIR] Dir is not a directory. 

[EFAULT] Spec or dir points outside the allocated address space of the pro¬ 

cess. 

[EBUSY] Dir is currently mounted on, is someone’s current working directory, 

or is otherwise busy. 

[EBUSY] The device associated with spec is currently mounted. 

[EBUSY] There are no more mount table entries. 



RETURN VALUE 

Upon successful completion a value of 0 is returned. Otherwise, a value of —1 is 
returned and errno is set to indicate the error. 
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SEE ALSO 

umount(2). 


2 


Icon International, Inc. 



MSGCTL(2) 


SYSTEM CALLS 


MSGCTL(2) 


NAME 

msgctl — message control operations 


SYNOPSIS 

^include <sys/types.h> 
#include <sys/ipc.h> 
#include <sys/msg.h> 


int msgctl (msqid, cmd, buf) 
int msqid, cmd; 
struct msqid_ds *buf; 


DESCRIPTION 

Msgctl provides a variety of message control operations as specified by cmd. The fol¬ 
lowing cmds are available: 

IPC_STAT Place the current value of each member of the data structure asso¬ 
ciated with msqid into the structure pointed to by buf. The con¬ 
tents of this structure are defined in intro( 2). {READ} 

IPCJSET Set the value of the following members of the data structure associ¬ 

ated with msqid to the corresponding value found in the structure 
pointed to by buf: 


msg_perm.uid 

msg_perm.gid 

msg_perm.mode /* only low 9 bits */ 
msg_qbytes 


This cmd can only be executed by a process that has an effective 
user ID equal to either that of super user or to the value of 
msg_perm.uid in the data structure associated with msqid. Only 
super user can raise the value of msg_qbytes. 

IPCLRMID Remove the message queue identifier specified by msqid from the 
system and destroy the message queue and data structure associ¬ 
ated with it. This cmd can only be executed by a process that has 
an effective user ID equal to either that of super user or to the value 
of msg_perm.uid in the data structure associated with msqid. 

Msgctl will fail if one or more of the following are true: 

pEINVAL] Msqid is not a valid message queue identifier. 

[EENVAL] Cmd is not a valid command. 

[EACCES] Cmd is equal to IPC_STAT and {READ} operation permission is 
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[EPERM] 


(EPERM] 

[EFAULT] 


denied to the calling process (see intro(2)). 

Cmd is equal to IPCLRMID or EPCJ5ET The effective user ID of the 
calling process is not equal to that of super user and it is not equal 
to the value of ma g p erm.uid in the data structure associated 
with msqid. 

Cmd is equal to IPCJ5ET, an attempt is being made to increase to 
the value of msg_qbytes, and the effective user ID of the calling 
process is not equal to that of super user. 

Buf points to an illegal-address. 


RETURN VALUE 

Upon successful completion, a value of 0 is returned. Otherwise, a value of —1 is 
returned and errno is set to indicate the error. 


SEE ALSO 

intro(2), msgget(2), msgop(2). 


fT" 
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NAME 

msgget — get message queue 


SYNOPSIS 

#include <sys/types.h> 
#in elude <sys/ipc.h> 
#in elude <sys/msg.h> 

int msgget (key, msgflg) 
key_t key; 
int msgflg; 


DESCRIPTION 

Msgget returns the message queue identifier associated with key. 

A message queue identifier and associated message queue and data structure (see 
intro{ 2)) are created for key if one of the following are true: 

10 Key is equal to IPC_PRIVATE 

Key does not already have a message queue identifier associated with it, and 
(msgflg & IPC_CREAT) is “true”. 


Upon creation, the data structure associated with the new message queue identifier 
is initialized as follows: 

Msg_perm.cuid, msg_perm.uid, msg_perm.egid, and msg_perm.gid are 
set equal to the effective user ID and effective group ID, respectively, of the 
calling process. 

The low-order 9 bits of msg_perm.mode are set equal to the low-order 9 
bits of msgflg. 

Msg_qnum, msgjbpid, msg_lrpid, msg_stime, and msg_rtime are set 

equal to 0. 

Msg_ctime is set equal to the current time. 

Msg_qbytes is set equal to the system limit. 


Msgget will fail if one or more of the following are true: 

[EACCES] A message queue identifier exists for key, but operation permission 

(see *ntro(2)) as specified by the low-order 9 bits of msgflg would not 
be granted. 

[ENOENT] A message queue identifier does not exist for key and (msgflg & 

IPC.CREAT) is “false”. 

[ENOSPC] A message queue identifier is to be created but the system-imposed 

limit on the maximum number of allowed message queue identifiers 
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system wide would be exceeded. 

fEEXIST] A message queue identifier exists for hey but ( (msgflg & IPCLCREAT) 

& ( msgflg & IPCLEXCL)) is “true”. 

RETURN VALUE 

Upon successful completion, a non-negative integer, namely a message queue 
identifier, is returned. Otherwise, a value of —1 is returned and errno is set to indi¬ 
cate the error. 


SEE ALSO 

intro(2), msgctl(2), msgop(2). 



2 


Icon International, Inc. 



MSG0P(2) 


SYSTEM CALLS 


MSGOP(2) 


NAME 

msgop — message operations 


SYNOPSIS 

^include <sys/types.h> 

#include <sys/ipe.h> 

#include <sys/msg.h> 

int msgsnd (msqid, msgp, msgsz, msgflg) 
int msqid; 

struct msgbuf *msgp; 
int msgsz, msgflg; 

int msgrcv (msqid, msgp, msgsz, msgtyp, msgflg) 
int msqid; 

struct msgbuf *msgp; 
int msgsz; 
long msgtyp; 
int msgflg; 


DESCRIPTION 

Msgsnd is used to send a message to the queue associated with the message queue 
identifier specified by msqid. {WRITE} Msgp points to a structure containing the mes¬ 
sage. This structure is composed of the following members: 

long mtype; /* message type */ 

char mtext[]; /* message text */ 


Mtype is a positive integer that can be used by the receiving process for message 
selection (see msgrcv belowj. Mtext is any text of length msgsz bytes. Msgsz can 
range from 0 to a system-imposed maximum. 

Msgflg specifies the action to be taken if one or more of the following are true: 

The number of bytes already on the queue is equal to msg_qbytes (see 
intro( 2)). 

The total number of messages on all queues system-wide is equal to the 
system-imposed limit. 

These actions are as follows: 

If (msgflg & IPO_NOWAIT) is “true”, the message will not be sent and the 
calling process will return immediately. 

If (msgflg & IPC_NOWAIT) is “false”, the calling process will suspend 
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execution until one of the following occurs: 

The condition responsible for the suspension no longer exists, in 
which case the message is sent. 

Msqid is removed from the system (see msgctl( 2)). When this occurs, 
errno is set equal to EIDRM, and a value of —1 is returned. 

The calling process receives a signal that is to be caught. In this 
case the message is not sent and the calling process resumes execu¬ 
tion in the manner prescribed in signal( 2)). 


Msgsnd will fail and no message will be sent if one or more of the following are true: 
[EINVAL] Msqid is not a valid message queue identifier. 

[EACCES] Operation permission is denied to the calling process (see infro(2)). 

[EINVAL] Mtype is less than 1. 

[EAGAIN] The message cannot be sent for one of the reasons cited above and 

(msgflg & IPCLNOWAIT) is “true”. 

[EINVAL] Msgsz is less than zero or greater than the system-imposed limit. 

[EFAULT] Msgp points to an illegal address. 

Upon successful completion, the following actions are taken with respect to the data 
structure associated with msqid (see intro (2)). 

Msg_qnum is incremented by 1. 

Mag lspid is set equal to the process ID of the calling process. 

Msg_stime is set equal to the current time. 

Msgrcv reads a message from the queue associated with the message queue identifier 
specified by msqid and places it in the structure pointed to by msgp. {READ} This 
structure is composed of the following members: 

long mtype; /* message type */ 

char mtext[]; /* message text */ 


Mtype is the received message’s type as specified by the sending process. Mtext is the 
text of the message. Msgsz specifies the size in bytes of mtext. The received message 
is truncated to msgsz bytes if it is larger than msgsz and ( msgflg & MSG_NOERROR) 
is “true”. The truncated part of the message is lost and no indication of the trunca¬ 
tion is given to the calling process. 

Msgtyp specifies the type of message requested as follows: 

If msgtyp is equal to 0, the first message on the queue is received. 

If msgtyp is greater than 0, the first message of type msgtyp is received. 

If msgtyp is less than 0, the first message of the lowest type that is less than 
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or equal to the absolute value of msgtyp is received. 

Msgflg specifies the action to be taken if a message of the desired type is not on the 
queue. These are as follows: 

If (msgflg & JPC_NOWAIT) is “true”, the calling process will return immedi¬ 
ately with a return value of —1 and errno set toENOMSG. 

If (msgflg & IPC_NOWAIT) is “false”, the calling process will suspend execu¬ 
tion until one of the following occurs: 

A message of the desired type is placed on the queue. 

Msqid is removed from the system. When this occurs, errno is set 
equal to EIDRM, and a value of —1 is returned. 

The calling process receives a signal that is to be caught. In this 
case a message is not received and the calling process resumes execu¬ 
tion in the manner prescribed in signal{ 2)). 


Msgrcv will fail and no message will be received if one or more of the following are 
true: 


[EINVAL] 

[EACCES] 

[EINVAL] 

[E2BIG] 

[ENOMSG] 

[EFAULT] 


Msqid is not a valid message queue identifier. 

Operation permission is denied to the calling process. 

Msgsz is less than 0. 

Mtext is greater than msgsz and (msgflg & MSG_NOERROR) is 
“false”. 

The queue does not contain a message of the desired type and 
(msgtyp & IPCJNOWAIT) is “true”. 

Msgp points to an illegal address. 


Upon successful completion, the following actions are taken with respect to the data 
structure associat ed w'ith msqid (see intro (2)). 

Msg_qnum is decremented by 1. 

Msg_lrpid is set equal to the process ID of the calling process. 

Msg_rtime is set equal to the current time. 


RETURN VALUES 

If msgsnd or msgrcv return due to the receipt of a signal, a value of —1 is returned to 
the calling process and errno is set to EINTR. If they return due to removal of msqid 
from the system, a value of —1 is returned and errno is set to EIDRM. 

Upon successful completion, the return value is as follows: 

Msgsnd returns a value of 0. 

Msgrcv returns a value equal to the number of bytes actually placed into 
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mtext. 

Otherwise, a value of —1 is returned and trrno is set to indicate the error. 

SEE ALSO 

intro(2), msgctl(2), msgget(2), signal(2). 
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NAME 

nice — change priority of a process 


SYNOPSIS 

int nice (incr) 
ini incr; 


DESCRIPTION 

Nice adds the value of incr to the nice value of the calling process. A process’s nice 
value is a positive number for which a more positive value results in lower CPU prior¬ 
ity. 

A maximum nice value of 39 and a minimum nice value of 0 are imposed by the sys¬ 
tem. Requests for values above or below these limits result in the nice value being 
set to the corresponding limit. 

[EPERM] Nice will fail and not change the nice value if incr is negative or 

greater than 40 and the effective user ID of the calling process is not 
super-user. 


RETURN VALUE 

Upon successful completion, nice returns the new nice value minus 20. Otherwise, a 
value of —1 is returned and errno is set to indicate the error. 


SEE ALSO 

exec(2). 

nice(l) in the ICON/UX User Reference Manual. 
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NAME 

open — open for reading or writing 


SYNOPSIS 

#include <fcntl.h> 

int open (path, ofi&g [, mode ] ) 

char *path; 

int oflag, mode; 


DESCRIPTION 

Path points to a path name naming a file. Open opens a file descriptor for the 
named file and sets the file status flags according to the value of oflag. Oflag values 
are constructed by or-ing flags from the following list (only one of the first three flags 
below may be used): 

CLRDONLY Open for reading only. 

0_WR0NLY Open for writing only. 

0_RDWR Open for reading and writing. 

CLNDELAY This flag may affect subsequent reads and writes. See read{ 2) and 
write(2). 

When opening a FIFO with O_RD0NLY or O.WRONLY set: 

If 0_NDELAY is set: 

An open for reading-only will return without delay. An open for 
writing-only will return an error if no process currently has the 
file open for reading. 

If 0_NDELAY is clear: 

An open for reading-only will block until a process opens the file 
for writing. An open for writing-only will block until a process 
opens the file for reading. 

When opening a file associated with a communication line: 

If CLNDELAY is set: 

The open will return without waiting for carrier. 

If CLNDELAY is clear: 

The open will block until carrier is present. 
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0_APPEND If set, the file pointer will be set to the end of the file prior to each 
write. 

CLCREAT If the file exists, this flag has no effect. Otherwise, the owner ID of the 
file is set to the effective user ID of the process, the group ID of the file is 
set to the effective group ID of the process, and the low-order 12 bits of 
the file mode are set to the value of mode modified as follows (see 
creat(2)): 


All bits set in the file anode creation mask of the process are 
cleared. See umwk(2). 

The t ' < save text image after executaem bit” of the mode is 
cleared. See chmod( 2»). 

0_TRUNC If the file exists, its length is truncated to © and the mode and owner 
are unchanged. 

OJEXCL If CLEXCL and Q_CREATasre set, open will fail if the file exists. 


The file pointer used to mark ths? .current position within the file is set to the begin¬ 
ning of the file. 


The new file descriptor is set to remain open across exec system calls. See fcntl( 2). 


The named file 

[ENOTDIR] 

[ENOENT] 

[EACCES] 

[EACCES] 

IE1SDIR] 

[EROFS) 

[EMFILEJ 

(ENXIO] 

JETXTBSY] 

[EFAULT] 

(EEXISTj 

(ENXIO) 

[EINTR] 

(ENFILE) 


is opened unless one ©r more of the following are true: 

A component of the path prefix is not a directory. 

0_CREAT is not set and the named file d®ss not exist. 

A component of the path prefix denies search permission. 

OJiag permission is dmied for the named file. 

The named file is a directory and oflag is write or read/write. 

The named file resides on a read-only file system and oflag is write 
or read/write. 

Twenty (20) file descriptors are ®arren% .open. 

The named file is a character special or Mock special file, and the 
device associated with this special file doesmot exist. 

The file is a pure procedure (shared text.) file that is being executed 
and oflag is write or read/write. 

Path points outside the allocated address space of the process. 
O.CREAT and OJEXCL are set, and the named file exists. 

0_NDELAY is set, the named file is a FIFO, O.WRONLY is set, and no 
process has the file open for reading. 

A signal was caught during the open system call. 

The system file table is full. 
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RETURN VALUE 

Upon successful completion, the file descriptor is returned. Otherwise, a value of —1 
is returned and errno is set to indicate the error. 

SEE ALSO 

chmod(2), close(2), creat(2), dup(2), fcntl(2), lseek(2), read(2), umask(2), write(2). 
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NAME 

ovride — set/clear hardware OVRIDE bit 


SYNOPSIS 

ovride(flag) 
int flag; 


DESCRIPTION 

The OVRIDE signal on the CPU3 board allows user processes to access address 
ranges outside of normal user space (0x0 - 0x40000000) without getting a bus error. 
The ovride() system call allows a user process to request OVRIDE privilege. The 
result is to allow a user mode process to access any memory or I/O device that is 
available in supervisor mode. This capability is potentially very dangerous if given a 
hostile or ill-behaved process. The caller of ovride() must therefore have super-user 
priviledges. Other bus errors, such as those for page faults or write violations, are 
not affected by OVRIDE. The OVRIDE bit is turned on when flag is non-zero, other¬ 
wise it is turned off. 


RETURN VALUE 

Zero is returned if the operation was successful; —1 is returned if an error occurs, 
with a more specific error code being placed in the global variable errno. 


ERRORS 

Ovride will fail if: 

[EPERM] The effective user ID is not the super-user. 
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NAME 

pause — suspend process until signal 


SYNOPSIS 

pause () 


DESCRIPTION 

Pause suspends the calling process until it receives a signal. The signal must be one 
that is not currently set to be ignored by the calling process. 

If the signal causes termination of the calling process, pause will not return. 

If the signal is caught by the calling process and control is returned from the signal- 
catching function (see signal(2)), the calling process resumes execution from the point 
of suspension; with a return value of —1 from pause and errno set to EINTR. 


SEE ALSO 

alarm(2), kill(2), signal(2), wait(2). 
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NAME 

pipe — create an interprocess channel 


SYNOPSIS 

int pipe (fildes) 
int fildes[2]; 


DESCRIPTION 

Pipe creates an I/O mechanism called a pipe and returns two file descriptors, 
fildes[ 0] and fildes[ lj. Fildes\0] is opened for reading and fildes[ 1] is opened for writ¬ 
ing. 

Up to 5120 bytes of data are buffered by the pipe before the writing process is 
blocked. A read only file descriptor /i/des[0] accesses the data written to fildes{ l] on 
a first-in-first-out (FIFO) basis. 

[EMFILE] Pipe will fail if 19 or more file descriptors are currently open. 

[ENFILE] The system file table is full. 

RETURN VALUE 

Upon successful completion, a value of 0 is returned. Otherwise, a value of —1 is 
returned and errno is set to indicate the error. 


SEE ALSO 

read(2), write(2). 

sh(l) in the ICON/UX User Reference Manual. 
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NAME 

plock — lock process, text, or data in memory 


SYNOPSIS 

^include <sys/lock.h> 

int plock (op) 
int op; 


DESCRIPTION 

Plock allows the calling process to lock its text segment (text lock), its data segment 
(data lock), or both its text and data segments (process lock) into memory. Locked 
segments are immune to all routine swapping. Plock also allows these segments to 
be unlocked. The effective user ID of the calling process must be super-user to use 
this call. Op specifies the following: 


PROCLOCK - 
TXTLOCK - 
DATLOCK - 
UNLOCK - 


lock text and data segments into memory (process lock) 
lock text segment into memory (text lock) 
lock data segment into memory (data lock) 
remove locks 


Plock will fail and not perform the requested operation if one or more of the follow¬ 
ing are true: 

[EPERM] The effective user ID of the calling process is not super-user. 

[EINVAL] Op is equal to PROCLOCK and a process lock, a text lock, or a data 

lock already exists on the calling process. 


[EINVAL] 

[EINVAL] 

[EINVAL] 


Op is equal to TXTLOCK and a text lock, or a process lock already 
exists on the calling process. 

Op is equal to DATLOCK and a data lock, or a process lock already 
exists on the calling process. 

Op is equal to UNLOCK and no type of lock exists on the calling 
process. 


RETURN VALUE 

Upon successful completion, a value of 0 is returned to the calling process. Other¬ 
wise, a value of —1 is returned and errno is set to indicate the error. 
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SEE ALSO 

exec(2), exit(2), fork(2). 
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NAME 

profil — execution time profile 


f 


SYNOPSIS 

void profil (buff, bufsiz, offset, scale) 
char *buff; 

int bufsiz, offset, scale; 


DESCRIPTION 

Buff points to an area of core whose length (in bytes) is given by bufsiz. After this 
call, the user’s program counter (pc) is examined each clock tick (60th second); offset 
is subtracted from it, and the result multiplied by scale. If the resulting number 
corresponds to a word inside buff, that word is incremented. 

The scale is interpreted as an unsigned, fixed-point fraction with binary point at the 
left: 0177777 (octal) gives a 1-1 mapping of pc’s to words in buff; 077777 (octal) maps 
each pair of instruction words together. 02(octal) maps all instructions onto the 
beginning of buff (producing a non-interrupting core clock). 

Profiling is turned off by giving a scale of 0 or 1. It is rendered ineffective by giving 
a bufsiz of 0. Profiling is turned off when an exec is executed, but remains on in child 
and parent both after a fork. Profiling will be turned off if an update in buff would 
cause a memory fault. 


RETURN VALUE 

Not defined. 


SEE ALSO 

monitor(3C). 

prof(l) in the ICON/UX User Reference Manual. 
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NAME 

ptrace — process trace 


SYNOPSIS 

^include <signal.h> 

ptrace(request, pid, addr, data) 
int request, pid, *addr, data; 


DESCRIPTION 

Ptrace provides a means by which a parent process may control the execution of a 
child process, and examine and change its core image. Its primary use is for the 
implementation of breakpoint debugging. There are four arguments whose interpre¬ 
tation depends on a request argument. Generally, pid is the process ID of the traced 
process, which must be a child (no more distant descendant) of the tracing process. 
A process being traced behaves normally until it encounters some signal whether 
internally generated like “illegal instruction” or externally generated like “inter¬ 
rupt”. See sigvec(2) for the list. Then the traced process enters a stopped state and 
its parent is notified via wait( 2). When the child is in the stopped state, its core 
image can be examined and modified using ptrace. If desired, another ptrace request 
can then cause the child either to terminate or to continue, possibly ignoring the sig¬ 
nal. 

The value of the request argument determines the precise action of the call: 

0 This request is the only one used by the child process; it declares that the pro¬ 
cess is to be traced by its parent. All the other arguments are ignored. Pecu¬ 
liar results will ensue if the parent does not expect to trace the child. 

1,2 The word in the child process’s address space at addr is returned. If I and D 
space are separated (e.g. historically on a pdp-ll), request 1 indicates I space, 2 
D space. Addr must be even. The child must be stopped. The input data is 
ignored. 

3 The word of the system’s per-process data area corresponding to addr is 
returned. Addr must be even and less than 512. This space contains the regis¬ 
ters and other information about the process; its layout corresponds to the user 
structure in the system. 

4,5 The given data is written at the word in the process’s address space correspond¬ 
ing to addr, which must be even. No useful value is returned. If I and D space 
are separated, request 4 indicates I space, 5 D space. Attempts to write in pure 
procedure fail if another process is executing the same file. 

6 The process’s system data is written, as it is read with request 3. Only a few 
locations can be written in this way: the general registers, the floating point 
status and registers, and certain bits of the processor status word. 

7 The data argument is taken as a signal number and the child’s execution contin¬ 
ues at location addr as if it had incurred that signal. Normally the signal 
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number will be either 0 to indicate that the signal that caused the stop should 
be ignored, or that value fetched out of the process’s image indicating which sig¬ 
nal caused the stop. If addr is (int *)1 then execution continues from where it 
stopped. 

8 The traced process terminates. 

9 Execution continues as in request 7; however, as soon as possible after execution 
of at least one instruction, execution stops again. The signal number from the 
stop is SIGTRAP. (On ICON systems the trace-bit is set and just one instruc¬ 
tion is executed.) This is part of the mechanism for implementing breakpoints. 

As indicated, these calls (except for request 0) can be used only when the subject 
process has stopped. The wait call is used to determine when a process stops; in such 
a case the “termination” status returned by wait has the value 0177 to indicate stop¬ 
page rather than genuine termination. 


To forestall possible fraud, ptrace inhibits the set-user-id and set-group-id facilities 
on subsequent execve(2) calls. If a traced process calls execve, it will stop before exe¬ 
cuting the first instruction of the new image showing signal SIGTRAP. 

On an ICON system, “word” also means a 32-bit integer, but the “even” restriction 
does not apply. 


RETURN VALUE 

A 0 value is returned if the call succeeds. If the call fails then a —1 is returned and 
the global variable errno is set to indicate the error. 


ERRORS 


[EINVAL] 

The 

[EINVAL] 

The 

[EINVAL] 

The 

[EFAULT] 

The 

[EPERM] 

The 


request code is invalid, 
specified process does not exist, 
given signal number is invalid, 
specified address is out of bounds, 
specified process cannot be traced. 


SEE ALSO 

wait(2), sigvec(2), adb(l) 


BUGS 


Ptrace is unique and arcane; it should be replaced with a special file which can be 
opened and read and written. The control functions could then be implemented with 
io,ctl{ 2) calls on this file. This would be simpler to understand and have much higher 
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performance. 

The request 0 call should be able to specify signals which are to be treated normally 
and not cause a stop. In this way, for example, programs with simulated floating 
point (which use “illegal instruction” signals at a very high rate) could be efficiently 
debugged. 

The error indication, —1, is a legitimate function value; errno, see intro( 2), can be 
used to disambiguate. 

It should be possible to stop a process on occurrence of a system call; in this way a 
completely controlled environment could be provided. 


( 
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NAME 

read — read from file 


SYNOPSIS 

int read (fildes, buf, nbyte) 
int fildes; 
char *buf; 
unsigned nbyte; 


DESCRIPTION 

Fildes is a file descriptor obtained from a creat, open, dup , fcntl, or pipe system call. 

Read attempts to read nbyte bytes from the file associated with fildes into the buffer 
pointed to by buf. 

On devices capable of seeking, the read starts at a position in the file given by the 
file pointer associated with fildes. Upon return from read, the file pointer is incre¬ 
mented by the number of bytes actually read. 

Devices that are incapable of seeking always read from the current position. The 
value of a file pointer associated with such a file is undefined. 

Upon successful completion, read returns the number of bytes actually read and 
placed in the buffer; this number may be less than nbyte if the file is associated with 
a communication line (see ioctl( 2) and termio(7)), or if the number of bytes left in the 
file is less than nbyte bytes. A value of 0 is returned when an end-of-file has been 
reached. 

When attempting to read from an empty pipe (or FIFO): 

If 0_NDELAY is set, the read will return a 0. 

If 0_NDELAY is clear, the read will block until data is written to the file or 
the file is no longer open for writing. 

When attempting to read a file associated with a tty that has no data currently 
available: 

If 0_NDELAY is set, the read will return a 0. 

If 0_NDELAY is clear, the read will block until data becomes available. 

Read will fail if one or more of the following are true: 

[EBADF] Fildes is not a valid file descriptor open for reading. 

[EFAULT] Buf points outside the allocated address space. 
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[EINTR] A signal was caught during the read system call. 


RETURN VALUE 

Upon successful completion a non-negative integer is returned indicating the number 
of bytes actually read. Otherwise, a —1 is returned and errno is set to indicate the 
error. 


SEE ALSO 

creat(2), dup(2), fcntl(2), ioctl(2), open(2), pipe(2). 
termio(7) in the ICON/UXV Administrator Reference Manual 
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NAME 

semctl — semaphore control operations 


SYNOPSIS 

#include <sys/types.h> 

#include <sys/ipc.h> 

^include <sys/sem.h> 

int semctl (semid, semnum, cmd, arg) 
int semid, cmd; 
int semnum; 
union semun { 
int val; 

struct semid_ds *buf; 
ushort *array; 

} arg; 


DESCRIPTION 

Semctl provides a variety of semaphore control operations as specified by cmd. 


The following cmds are executed with respect to the semaphore specified by semid 
and semnum: 


GETVAL 

SETVAL 


GETPID 

GETNCNT 

GETZCNT 


Return the value of semval (see intro(2)). {READ} 

Set the value of semval to arg.val. {ALTER} When this cmd is 
successfully executed, the semadj value corresponding to the 
specified semaphore in all processes is cleared. 

Return the value of sempid. {READ} 

Return the value of semncnt. {READ} 

Return the value of semzcnt. {READ} 


The following cmds return and set, respectively, every semval in the set of sema¬ 
phores. 


GETALL Place semvals into array pointed to by arg. array. {READ} 

SETALL Set semvals according to the array pointed to by arg. array. 

{ALTER} When this cmd is successfully executed the semadj 
values corresponding to each specified semaphore in all 
processes are cleared. 
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( 


The following cmds are also available: 

Place the current value of each member of the data structure 
associated with semid into the structure pointed to by arg.buf. 
The contents of this structure are defined in intro( 2). {READ} 

Set the value of the following members of the data structure 
associated with semid to the corresponding value found in the 
structure pointed to by arg.buf : 

sem_perm.uid 
sem_perm.gid 

sem_perm.mode /* only low 9 bits */ 

This cmd can only be executed by a process that has an 
effective user ID equal to either that of super-user or to the 
value of sem_perm.uid in the data structure associated with 
semid. 

IPC_RMID Remove the semaphore identifier specified by semid from the 
system and destroy the set of semaphores and data structure 
associated with it. This cmd can only be executed by a pro¬ 
cess that ias an effective user ID equal to either that of super- 
user or to the value of sem_perm.uid in the data structure 
associated with semid. 

Semctl will fail if one or more of the following are true: 

[EINVAL] Semid is not a valid semaphore identifier. 

[EINVAL] Semnum is less than zero or greater than sem_nsems. 

[EINVAL] Cmd is not a valid command. 

[EACCES] Operation permission is denied to the calling process (see 

intro( 2)). 

[ERANGE] Cmd isSETVAL or SETALL and the value to which semval is 

to be set is greater than the system imposed maximum. 

[EPERM] Cmd is equal to IPC_RMID or IPC_SET and the effective user 

ID of the calling process is not equal to that of super-user 
and it is not equal to the value of sem_perm.uid in the 
data structure associated with semid. 

[EFAULT] Arg.buf points to an illegal address. 


IPC_STAT 

IPC_SET 



RETURN VALUE 

Upon successful completion, the value returned depends on cmd as follows: 

GETVAL The value of semval. 

GETPID The value of sempid. 
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GETNCNT The value of semncnt. 

GETZONT The value of semzcnt. 

All others A value of 0. 

Otherwise, a value of —1 is returned and errno is set to indicate the error. 

SEE ALSO 

intro(2), semget(2), semop(2). 
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NAME 

semget — get set of semaphores 


SYNOPSIS 

^include <sys/types.h> 
^include <sys/ipc.h> 

#include <sys/sem.h> 

int semget (key, nsems, semflg) 

key_t key; 

int nsems, semflg; 


DESCRIPTION 

Semget returns the semaphore identifier associated with key. 


A semaphore identifier and associated data structure and set containing nsems sema¬ 
phores (see intro(2)) are created for key if one of the following are true: 

Key is equal to IPCJPRIVATE 

Key does not already have a semaphore identifier associated with it, and 
(semflg & IPCLCREAT) is “true”. 


Upon creation, the data structure associated with the new semaphore identifier is 
initialized as follows: 

Sem_perm.cuid, sem_perm.uid, sem_perm.cgid, and sem_perm.gid are 

set equal to the effective user ID and effective group ID, respectively, of the 
calling process. 

The low-order 9 bits of sem_perm.mode are set equal to the low-order 9 
bits of semflg. 

Sem_nsems is set equal to the value of nsems. 

Sem_otime is set equal to 0 and sem_ctime is set equal to the current time. 


Semget will fail if one or more of the following are true: 


[EINVAL] 

[EACCES] 

[EINVAL] 

[ENOENT] 


Nsems is either less than or equal to zero or greater than the 
system-imposed limit. 

A semaphore identifier exists for key, but operation permission (see 
intro(2 )) as specified by the low-order 9 bits of semflg would not be 
granted. 

A semaphore identifier exists for key, but the number of semaphores 
in the set associated with it is less than nsems and nsems is not 
equal to zero. 

A semaphore identifier does not exist for key and ( semflg & 
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EPC_CREAT) is “false”. 

[ENOSPC] A semaphore identifier is to be created but the system-imposed limit 

on the maximum number of allowed semaphore identifiers system 
wide would be exceeded. 

[ENOSPC] A semaphore identifier is to be created but the system-imposed limit 

on the maximum number of allowed semaphores system wide would 
be exceeded. 

[EEXIST] A semaphore identifier exists for key but ( (semflg & IPCLCREAT) 

and ( semflg & IPC_EXCL)) is “true”. 


RETURN VALUE 

Upon successful completion, a non-negative integer, namely a semaphore identifier, is 
returned. Otherwise, a value of —1 is returned and errno is set to indicate the error. 


SEE ALSO 

intro(2), semctl(2), semop(2). 
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NAME 

semop — semaphore operations 


SYNOPSIS 

#inelude <sys/types.h> 

#inelude <sys/ipc.h> 
#include <sys/sem.h> 

int semop (semid, sops, nsops) 
int semid; 

struct sembuf **sops; 
int nsops; 


DESCRIPTION 

Semop is used to automatically perform an array of semaphore operations on the set 
of semaphores associated with the semaphore identifier specified by semid . Sops is a 
pointer to the array of semaphore-operation structures. Nsops is the number of such 
structures in the array. The contents of each structure includes the following 
members: 

short semjium; /* semaphore number */ 

short sem_op; /* semaphore operation */ 

short sem_flg; /* operation flags */ 


Each semaphore operation specified by sem^op is performed on the corresponding 
semaphore specified by semid and sem^num. 

Sem^op specifies one of three semaphore operations as follows: 

If sem^op is a negative integer, one of the following will occur: {ALTER} 

If semval (see intro(2)) is greater than or equal to the absolute value 
of sem^op, the absolute value of sem^op is subtracted from semval. 
Also, if (sem^Jlg & SEM.UNDO) is “true”, the absolute value of 
sem^op is added to the calling process’s semadj value (see exit( 2)) for 
the specified semaphore. 

If semval is less than the absolute value of sem^op and (sem^g & 
IPC^NOWAIT) is “true”, semop will return immediately. 

If semval is less than the absolute value of sem^op and {sem^Jig & 
IPC_NOWAIT) is “false”, semop will increment the semnent associ¬ 
ated with the specified semaphore and suspend execution of the cal¬ 
ling process until one of the following conditions occur. 
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Semval becomes greater than or equal to the absolute value of 
sern^op. When this occurs, the value of semncnt associated with 
the specified semaphore is decremented, the absolute value of 
stm_op is subtracted from semval and, if ( sem_flg & SEM_UNDO) 
is “true”, the absolute value of aem_op is added to the calling 
process’s semadj value for the specified semaphore. 

The semid for which the calling process is awaiting action is 
removed from the system (see semctl{ 2)). When this occurs, errno 
is set equal to EIDRM, and a value of —1 is returned. 

The calling process receives a signal that is to be caught. When 
this occurs, the value of semncnt associated with the specified 
semaphore is decremented, and the calling process resumes execu¬ 
tion in the manner prescribed in signal( 2). 


If eem_op is a positive integer, the value of sem^op is added to semval and, 
if (sem_flg & SEM_UNDO) is “true”, the value of sem^op is subtracted from 
the calling process’s semadj value for the specified semaphore. {ALTER} 

If sem_op is zero, one of the following will occur: {READ} 

If semval is zero, semop will return immediately. 

If semval is not equal to zero and (sem^flg & IPC_NOWAIT) is 
“true”, semop will return immediately. 

If semval is not equal to zero and (sem^flg & IPC_NOWAIT) is 
“false”, semop will increment the semzcnt associated with the 
specified semaphore and suspend execution of the calling process 
until one of the following occurs: 


Semval becomes zero, at which time the value of semzcnt associ¬ 
ated with the specified semaphore is decremented. 

The semid for which the calling process is awaiting action is 
removed from the system. When this occurs, errno is set equal to 
EIDRM, and a value of —1 is returned. 

The calling process receives a signal that is to be caught. When 
this occurs, the value of semzcnt associated with the specified 
semaphore is decremented, and the calling process resumes execu¬ 
tion in the manner prescribed in signal(2). 


Semop will fail if one or more of the following are true for any of the semaphore 
operations specified by sops : 

[EINVAL] Semid is not a valid semaphore identifier. 
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[EFBIG] 

[E2BIG] 

[EACCES] 

[EAGAIN] 

[ENOSPC] 

[EINVAL] 

[ERANGE] 

[ERANGE] 

[EFAULT] 


Sem_num is less than zero or greater than or equal to the number 
of semaphores in the set associated with semid. 

Nsops is greater than the system-imposed maximum. 

Operation permission is denied to the calling process (see intro(2)). 

The operation would result in suspension of the calling process but 
(semjlg & EPC_NOWAIT) is “true”. 

The limit on the number of individual processes requesting an 
SEM_UNDO would be exceeded. 

The number of individual semaphores for which the calling process 
requests a SEM_UNDO would exceed the limit. 

An operation would cause a semval to overflow the system-imposed 
limit. 

An operation would cause a semadj value to overflow the system- 
imposed limit. 

Sops points to an illegal address. 


Upon successful completion, the value of sempid for each semaphore specified in the 
array pointed to by sops is set equal to the process ID of the calling process. 


RETURN VALUE 

If semop returns due to the receipt of a signal, a value of —1 is returned to the cal¬ 
ling process and errno is set to EINTR. If it returns due to the removal of a semid 
from the system, a value of —1 is returned and errno is set to EIDRM. 

Upon successful completion, the value of semval at the time of the call for the last 
operation in the array pointed to by sops is returned. Otherwise, a value of —1 is 
returned and errno is set to indicate the error. 


SEE ALSO 

exec(2), exit(2), fork(2), intro(2), semctl(2), semget(2). 
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NAME 

setpgrp — set process group ID 


SYNOPSIS 

int setpgrp ( ) 


DESCRIPTION 

Setpgrp sets the process group ID of the calling process to the process ID of the calling 
process and returns the new process group ID. 


RETURN VALUE 

Setpgrp returns the value of the new process group ID. 


SEE ALSO 

exec(2), fork(2), getpid(2), intro(2), kill(2), signal(2). 
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NAME 

setuid, setgid — set user and group IDs 


SYNOPSIS 

int setuid (uid) 
int uid; 

int setgid (gid) 
int gid; 


DESCRIPTION 

Setuid (setgid ) is used to set the real user (group) ID and effective user (group) ID of 
the calling process. 

If the effective user ID of the calling process is super-user, the real user (group) ID and 
effective user (group) ID are set to uid (gid). 

If the effective user ID of the calling process is not super-user, but its real user 
(group) ID is equal to uid (gid), the effective user (group) ID is set to uid (gid). 

If the effective user ID of the calling process is not super-user, but the saved set-user 
(group) ID from exec( 2) is equal to uid (gid), the effective user (group) ID is set to uid 
(gid). 

Setuid (setgid) will fail if the real user (group) ID of the calling process is not equal to 
uid (gid) and its effective user ID is not super-user. [EPERM] 

The uid is out of range. [EINVAL] 


RETURN VALUE 

Upon successful completion, a value of 0 is returned. Otherwise, a value of —1 is 
returned and errno is set to indicate the error. 


SEE ALSO 

getuid(2), intro(2). 
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SHMCTL (2) 


NAME 

shmctl — shared memory control operations 


SYNOPSIS 

#include <sys/types.h> 
#include <sys/ipc.h> 
^include <sys/shm.h> 

int shmctl (shmid, cmd, buf) 
int shmid, cmd; 
struct shmid_ds *buf; 


DESCRIPTION 

Shmctl provides a variety of shared memory control operations as specified by cmd. 
The following cmds are available: 


IPC_STAT Place the current value of each member of the data structure 
associated with shmid into the structure pointed to by buf. The 
contents of this structure are defined in [EINVAL] intro(2). 
{READ} 

IPC_SET Set the value of the following members of the data structure 
associated with shmid to the corresponding value found in the 
structure pointed to by buf: 

shm_perm.uid 

shm_perm.gid 

shm_perm.mode /* only low 9 bits */ 


This cmd can only be executed by a process that has an effective 
user ID equal to either that of super-user or to the value of 
shm_perm.uid in the data structure associated with shmid. 

IPCLRMID Remove the shared memory identifier specified by shmid from 
the system and destroy the shared memory segment and data 
structure associated with it. This cmd can only be executed by 
a process that has an effective user ID equal to either that of 
super-user or to the value of shm_perm.uid in the data struc¬ 
ture associated with shmid. 

SHM_LOCK Lock the shared memory segment specified by shmid in memory. 

This cmd can only be executed by a process that has an effective 
usr ID equal to super-user. 

SHM_UNLOCK 

Unlock the shared memory segment specified by shmid. This 
cmd can only be executed by a process that has an effective usr 
ID equal to super-user. 
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Shmctl will fail if one or more of the following are true: 

Shmid is not a valid shared memory identifier. [EINVAL] 

Cmd is not a valid command. [EINVAL] 

Cmd is equal to IPCJ5TAT and {READ} operation permission is denied 
to the calling process [see intro(2)j. [EACCES] 

Cmd is equal to EPCLRMID or IPCjSET and the effective user ID of the 
calling process is not equal to that of super-user and it is not equal to 
the value of shm_perm.uid in the data structure associated with 
shmid. [EPERM] 

Cmd is equal to SHMJLOCK or SHM_UNLOCK and the effective user ID 
of the calling process is not equal to that of super-user. [EPERM] 

Cmd is equal to SHM_UNLOCK and the shared-memory segment 
specified by shmid is not locked in memory. [EINVAL] Buf points to an 
illegal address. [EFAULT] 


RETURN VALUE 

Upon successful completion, a value of 0 is returned. Otherwise, a value of —1 is 
returned and errno is set to indicate the error. 


SEE ALSO 

shmget(2), shmop(2). 
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SYSTEM CALLS 


SHMGET (2) 


NAME 

shmget — get shared memory segment 


SYNOPSIS 

^include <sys/types 
^include <sys/ipc.h> 
^include <sys/shm.h> 

int shmget (key, size, shmflg) 

key_t key; 

int size, shmflg; 


DESCRIPTION 

Shmget returns the shared memory identifier associated with key. 

A shared memory identifier and associated data structure and shared memory seg¬ 
ment of size size bytes (see intro{2)) are created for key if one of the following are 
true: 

Key is equal to IPCLPRIVATE 

Key does not already have a shared memory identifier associated with it, and 
{shmflg & IPCLCREAT) is “true”. 

Upon creation, the data structure associated with the new shared memory identifier 
is initialized as follows: 

Shm_perm.cuid, shm_perm.uid, shm_perm.cgid, and shm_perm.gid 

are set equal to the effective user ID and effective group ID, respectively, of the 
calling process. 

The low-order 9 bits of shm_permjnode are set equal to the low-order 9 
bits of shmflg. Shm_j»egsz is set equal to the value of size. 

Shm_lpid, shm_nattch, shm_atime, and shm_dtime are set equal to 0. 

Shm_ctime is set equal to the current time. 

Shmget will fail if one or more of the following are true: 

(EINVAL] Size is less than the system-imposed minimum or greater than the 

system-imposed maximum. 

[EACCES] A shared memory identifier exists for key but operation permission 

(see intro{ 2)) as specified by the low-order 9 bits of shmflg would not 
be granted. 

[EINVAL] A shared memory identifier exists for key but the size of the seg¬ 

ment associated with it is less than size and size is not equal to 
zero. 
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[ENOENT] 

(ENOSPC] 

IENOMEM] 

[EEXIST] 


A shared memory identifier does not exist for key and (shmflg & 
IPCLCREAT) is “false”. 

A shared memory identifier is to be created but the system-imposed 
limit on the maximum number of allowed shared memory identifiers 
system wide would be exceeded. 

A shared memory identifier and associated shared memory segment 
are to be created but the amount of available physical memory is 
not sufficient to fill the request. 

A shared memory identifier exists for key but ( (shmflg & 
IPC_CREAT) and ( shmflg & IPCLEXCL) ) is “true”. 


RETURN VALUE 

Upon successful completion, a non-negative integer, namely a shared memory 
identifier is returned. Otherwise, a value of —1 is returned and errno is set to indi¬ 
cate the error. 


SEE ALSO 

intro(2), shmctl(2), shmop(2). 


( 
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SHMOP (2) 


NAME 

shmop — shared memory operations 


SYNOPSIS 

^include <8ys/types.h> 

^include <sys/ipc.h> 

^include <sys/shm.h> 

char *shmat (shmid, shmaddr, shmflg) 
int shmid; 
char *shmaddr 
int shmflg; 

int shmdt (shmaddr) 
char *shmaddr 


DESCRIPTION 

Shmat attaches the shared memory segment associated with the shared memory 
identifier specified by shmid to the data segment of the calling process. The segment 
is attached at the address specified by one of the following criteria: 

If shmaddr is equal to zero, the segment is attached at the first available 
address as selected by the system. 

If shmaddr is not equal to zero and ( shmflg & SHMJRND) is “true”, the seg¬ 
ment is attached at the address given by ( shmaddr - (shmaddr modulus 
SHMLBA)). 

If shmaddr is not equal to zero and (shmflg & SHM_RND) is “false”, the seg¬ 
ment is attached at the address given by shmaddr. 


The segment is attached for reading if (shmflg & SHM_RDONLY) is “true” {READ}, 
otherwise it is attached for reading and writing {READ/WRITE}. 


Shmat will fail and not attach the shared memory segment if one or more of the fol¬ 
lowing are true: 


[EINVAL] 

[EACCES] 

[ENOMEM] 

[EINVAL] 

[EINVAL] 

[EMFILE] 


Shmid is not a valid shared memory identifier. 

Operation permission is denied to the calling process (see intro( 2)). 

The available data space is not large enough to accommodate the 
shared memory segment. 

Shmaddr is not equal to zero, and the value of (shmaddr - (shmaddr 
modulus SHMLBA)) is an illegal address. 

Shmaddr is not equal to zero, (shmflg & SHMJtND) is “false”, and 
the value of shmaddr is an illegal address. 

The number of shared memory segments attached to the calling 
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[EINVAL] 

[EINVAL] 


process would exceed the system-imposed limit. 

Shmdt detaches from the calling process’s data segment the shared 
memory segment located at the address specified by shmaddr. 

Shmdt will fail and not detach the shared memory segment if 
shmaddr is not the data segment start address of a shared memory 
segment. 
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RETURN VALUES 

Upon successful completion, the return value is as follows: 

Shmat returns the data segment start address of the attached shared memory 
segment. 

Shmdt returns a value of 0. 

Otherwise, a value of —1 is returned and errno is set to indicate the error. 


SEE ALSO 

exec(2), exit(2), fork(2), intro(2), shmctl(2), shmget(2). 


Icon International, Inc. 



SIGNAL (2) 


SYSTEM CALLS 


SIGNAL (2) 


NAME 

signal — specify what to do upon receipt of a signal 


SYNOPSIS 

#include <signal.h> 


int (*signal (sig, func))() 
int sig; 

void (*func)(); 


DESCRIPTION 

Signal allows the calling process to choose one of three ways in which it is possible to 
handle the receipt of a specific signal. Sig specifies the signal and func specifies the 
choice. 


Sig can be assigned any one of the following except SIGKILL: 


SIGHUP 

01 

hangup 

SIGINT 

02 

interrupt 

SIG QUIT 

03* 

quit 

SIGILL 

04* 

illegal instruction (not reset when caught) 

SIGTRAP 

05* 

trace trap (not reset when caught) 

SIGIOT 

06* 

IOT instruction 

SIGEMT 

07* 

EMT instruction 

SIGFPE 

08* 

floating point exception 

SIGKILL 

09 

kill (cannot be caught or ignored) 

SIGBUS 

10* 

bus error 

SIGSEGV 

11* 

segmentation violation 

SIGSYS 

12* 

bad argument to system call 

SIGPIPE 

13 

write on a pipe with no one to read it 

SIGALRM 

14 

alarm clock 

SIGTERM 

15 

software termination signal 

SIGUSR1 

16 

user-defined signal 1 

SIGUSR2 

17 

user-defined signal 2 

SIGCLD 

18 

death of a child 



(see WARNING below) 

SIGPWR 

19 

power fail 


(see WARNING below) 


See below for the significance of the asterisk (*) in the above list. 


Func is assigned one of three values: SIG_DFL, SIGJGN, or a function address. 
The actions prescribed by these values are as follows: 
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SIG_DFL — terminate process upon receipt of a signal 

Upon receipt of the signal sig, the receiving process is to be terminated 
with all of the consequences outlined in exit(2). In addition a “core 
image” will be made in the current working directory of the receiving 
process if sig is one for which an asterisk appears in the above list and 
the following conditions are met: 


The effective user ID and the real user ID of the receiving process 
are equal. 

An ordinary file named core exists and is writable or can be 
created. If the file must be created, it will have the following 
properties: 


a mode of 0666 modified by the file creation mask (see 
umask(2)) 


a file owner ID that is the same as the effective user ID 
of the receiving process. 

a file group ID that is the same as the effective group ID 
of the receiving process 


SIG_IGN — ignore signal 

The signal sig is to be ignored. 

Note: the signal SIGKILL cannot be ignored. 


function address — catch signal 

Upon receipt of the signal sig, the receiving process is to execute the signal- 
catching function pointed to by func. The signal number sig will be passed 
as the only argument to the signal-catching function. Additional arguments 
are passed to the signal-catching function for hardware-generated signals. 
Before entering the signal-catching function, the value of func for the 
caught signal will be set to SIGJDFL unless the signal is SIGILL, SIGTRAP, or 
SIGPWR 


Upon return from the signal-catching function, the receiving process will 
resume execution at the point it was interrupted. 
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When a signal that is to be caught occurs during a read, a write, an open, 
or an ioctl system call on a slow device (like a terminal; but not a file), dur¬ 
ing a pause system call, or during a wait system call that does not return 
immediately due to the existence of a previously stopped or zombie process, 
the signal catching function will be executed and then the interrupted sys¬ 
tem call may return a —1 to the calling process with errno set to EINTR. 

Note: The signal SIGKILL cannot be caught. 


A call to signal cancels a pending signal sig except for a pending SIGKILL signal. 
Signal will fail if sig is an illegal signal number, including SIGKILL [EINVAL] 


RETURN VALUE 

Upon successful completion, signal returns the previous value of June for the specified 
signal sig. Otherwise, a value of —1 is returned and errno is set to indicate the 
error. 


SEE ALSO 

kill(2), pause(2), ptrace(2), wait(2), setjmp(3C). 
kill(l) in the ICON/UX User Reference Manual. 


WARNING 

Two other signals that behave differently than the signals described above exist in 
this release of the system; they are: 

SIGCLD 18 death of a child (reset when caught) 

SIGPWR 19 power fail (not reset when caught) 


There is no guarantee that, in future releases of the UNIX system, these signals will 
continue to behave as described below; they are included only for compatibility with 
other versions of the UNIX system. Their use in new programs is strongly 
discouraged. 


For these signals, June is assigned one of three values: SIG_DFL, SIGJGN, or a 
function address. The actions prescribed by these values of are as follows: 
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SIG_DFL - ignore signal 

The signal is to be ignored. 


SIG_IGN - ignore signal 

The signal is to be ignored. Also, if sig is SIGCLD, the calling process’s 
child processes will not create zombie processes when they terminate; see 
exit{2). 


function address - catch signal 

If the signal is SIGPWR, the action to be taken is the same as that 
described above for June equal to function address. The same is true if 
the signal is SIGCLD except, that while the process is executing the 
signal-catching function, any received SIGCLD signals will be queued and 
the signal-catching function will be continually reentered until the queue 
is empty. 


The SIGCLD affects two other system calls (wait(2), and exit{ 2)) in the following 
ways: 

wait If the func value of SIGCLD is set to SIGJGN and a wait is executed, the 
wait will block until all of the calling process’s child processes terminate; 
it will then return a value of —1 with errno set to ECHILD 

exit If in the exiting process’s parent process the func value of SIGCLD is set 
to SIGJGN, the exiting process will not create a zombie process. 

When processing a pipeline, the shell makes the last process in the pipeline the 
parent of the proceeding processes. A process that may be piped into in this 
manner (and thus become the parent of other processes) should take care not to 
set SIGCLD to be caught. 
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NAME 

stat, fstat — get file status 


SYNOPSIS 

^include <sys/types.h> 
^include <sys/stat.h> 

int stat (path, buf) 
char *path; 
struct stat *buf; 

int fstat (fildes, buf) 
int fildes; 
struct stat *buf; 


DESCRIPTION 

Path points to a path name naming a file. Read, write, or execute permission of the 
named file is not required, but all directories listed in the path name leading to the 
file must be searchable. Stat obtains information about the named file. 

Similarly, fstat obtains information about an open file known by the file descriptor 
fildes, obtained from a successful open, creat, dup, fcntl, or pipe system call. 

Buf is a pointer to a slat structure into which information is placed concerning the 
file. 


The contents of the structure pointed to by buf include the following members: 


ushort 

st_mode 

ino_t 

stjino; 

dev_t 

st_dev; 

dev_t 

st_rdev; 


short 

st_nlink; 

ushort 

st_uid; 

ushort 

st_gid; 

off_t 

st_size; 

time_t 

st_atime; 

time_t 

st_mtime 

time_t 

st_ctime; 


/* File mode; see mknod{ 2) */ 

/* Inode number */ 

/* ID of device containing */ 

/* a directory entry for this file */ 

/* ID of device */ 

/* This entry is defined only for */ 

/* character special or block special files */ 
/* Number of links */ 

/* User ID of the file’s owner */ 

/* Group ID of the file’s group */ 

/* File size in bytes */ 

/* Time of last access */ 

/* Time of last data modification */ 

/* Time of last file status change */ 

/* Times measured in seconds since */ 

/* 00:00:00 GMT, Jan. 1, 1970 */ 


Icon International, Inc. 


1 



STAT (2) 


SYSTEM CALLS 


STAT (2) 


st_atime Time when file data was last accessed. Changed by the following system 
calls: creat( 2), mknod(2), pipe(2), utime(2), and read(2). 

st_mtime Time when data was last modified. Changed by the following system 
calk: creat( 2), mknod{ 2), pipe{2), utime( 2), and write( 2). 

st_ctime Time when file status was last changed. Changed by the following system 
calls: chmod{ 2), chown{ 2), crea<(2), link( 2), mknod{2), pipe(2), unlink(2), 
utime(2), and write(2). 


Stat will fail if one or more of the following are true: 

[ENOTDIR] A component of the path prefix is not a directory. 

[ENOENT] The named file does not exist. 

[EACCES] Search permission is denied for a component of the path prefix. 

[EFAULT] Buf or path points to an invalid address. 


Fstat will fail if one or more of the following are true: 
[EBADF] Fildes is not a valid open file descriptor. 

[EFAULT] Buf points to an invalid address. 


RETURN VALUE 

Upon successful completion a value of 0 is returned. Otherwise, a value of —1 is 
returned and errno is set to indicate the error. 


SEE ALSO 

chmod(2), chown(2), creat(2), link(2), mknod(2), pipe(2), read(2), time(2), unlink(2), 
utime(2), write(2). 
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NAME 

stime — set time 


SYNOPSIS 

int stime (tp) 
long *tp; 


DESCRIPTION 

Stime sets the system’s idea of the time and date. Tp points to the value of time as 
measured in seconds from 00:00:00 GMT January 1, 1970. 

[EPERM] Stime will fail if the effective user ID of the calling process is not 

super-user. 


RETURN VALUE 

Upon successful completion, a value of 0 is returned. Otherwise, a value of —1 is 
returned and errno is set to indicate the error. 


SEE ALSO 

time(2). 
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NAME 

swrite — synchronous write on a file 


SYNOPSIS 

int swrite (fildes, buf, nbyte) 
int fildes; 
char *buf; 
unsigned nbyte; 


DESCRIPTION 

Fildes is a file descriptor obtained from a creat, open, dup, or fcntl system call. 

Swrite attempts to write nbyte bytes from the buffer pointed to by buf to the file 
associated with the fildes. 


The Swrite command blocks until the buffer has actually been written to the device. 
On files which are not associated with block devices, swrite behaves exactly the same 
as write{2). 

Swrite will fail if one or more of the following are true: 

[EBADF] Fildes is not a valid file descriptor open for writing. 

[EPIPE and SIGPIPE signal] 

An attempt is made to write to a pipe that is not open for reading 
by any process. 

[EFBIG] An attempt was made to write a file that exceeds the process’s file 

size limit or the maximum file size. See ulimit( 2). 

[EFAULT] Buf points outside the process’s allocated address space. 

[EINTR] A signal was caught during the swrite system call. 

If a swrite requests that more bytes be written than there is room for (e.g., the 
ulimit (see ulimit(2)) or the physical end of a medium), only as many bytes as there 
is room for will be written. For example, suppose there is space for 20 bytes more in 
a file before reaching a limit. A write of 512 bytes will return 20. The next write of 
a non-zero number of bytes will give a failure return (except as noted below). 


RETURN VALUE 

Upon successful completion the number of bytes actually written is returned. Other¬ 
wise, —1 is returned and errno is set to indicate the error. 
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SEE ALSO 

write (2), creat(2), dup(2), lseek(2), open(2), pipe(2), ulimit(2). 


SWRITE (2) 
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NAME 

sync — update super-block 


SYNOPSIS 

void sync ( ) 


DESCRIPTION 

Sync causes all information in memory that should be on disk to be written out. 
This includes modified super blocks, modified i-nodes, and delayed block I/O. 

It should be used by programs which examine a file system, for example fsck, df, etc. 
It is mandatory before a boot. 

The writing, although scheduled, is not necessarily complete upon return from sync. 


Icon International, Inc. 


1 



TIME (2) 


SYSTEM CALLS 


TIME(2) 


NAME 

time — get time 


SYNOPSIS 

long time ((long *) 0) 

long time (tloc) 
long *tloc; 


DESCRIPTION 

Time returns the value of time in seconds since 00:00:00 GMT, January 1, 1970. 

If tloc (taken as an integer) is non-zero, the return value is also stored in the location 
to which tloc points. 

[EFAULT] Time will fail if tloc points to an illegal address. 

RETURN VALUE 

Upon successful completion, time returns the value of time. Otherwise, a value of —1 
is returned and errno is set to indicate the error. 


SEE ALSO 

stime(2). 
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NAME 

times — get process and child process times 


SYNOPSIS 

#include <sys/types.h> 
#inelude <sys/times.h> 

long times (buffer) 
struct tms *buffer; 


DESCRIPTION 

Times fills the structure pointed to by buffer with time-accounting information. The 
following are the contents of this structure: 

struct tms { 

time_t tms_utime; 
time_t tms_stime; 
time_t tms_cutime; 
time_t tms_cstime; 

}; 

This information comes from the calling process and each of its terminated child 
processes for which it has executed a wait. All times are in 60ths of a second on DEC 
processors, lOOths of a second on AT&T processors. 


Tms^utime is the CPU time used while executing instructions in the user space of the 
calling process. 

Tms^stime is the CPU time used by the system on behalf of the calling process. 
Tms^cutime is the sum of the tms^utime s and tms^cutime s of the child processes. 
Tms^cstime is the sum of the tms^stime s and tms^cstime s of the child processes. 
[EFAULT] Times will fail if buffer points to an illegal address. 

RETURN VALUE 

Upon successful completion, times returns the elapsed real time, in 60ths (lOOths) of 
a second, since an arbitrary point in the past (e.g., system start-up time). This point 
does not change from one invocation of times to another. If times fails, a —1 is 
returned and errno is set to indicate the error. 
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SEE ALSO 

exec(2), fork(2), time(2), wait(2). 
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NAME 

ulimit — get and set user limits 


SYNOPSIS 

long ulimit (cmd, newlimit) 
int cmd; 
long newlimit; 


DESCRIPTION 

This function provides for control over process limits. The cmd values available are: 

1 Get the file size limit of the process. The limit is in units of 512-byte blocks 
and is inherited by child processes. Files of any size can be read. 

„ 2 Set the file size limit of the process to the value of newlimit. Any process may 

decrease this limit, but only a process with an effective user ID of super-user 
may increase the limit. Ulimit will fail and the limit will be unchanged if a 
process with an effective user ID other than super-user attempts to increase its 
file size limit. [EPERM] 

3 Get the maximum possible break value. See brk(2). 


RETURN VALUE 

Upon successful completion, a non-negative value is returned. Otherwise, a value of 
—1 is returned and errno is set to indicate the error. 


SEE ALSO 

brk(2), write(2). 
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NAME 

umask — set and get file creation mask 


SYNOPSIS 

int umask (cmask) 
int cmask; 


DESCRIPTION 

Umask sets the process’s file mode creation mask to cmask and returns the previous 
value of the mask. Only the low-order 9 bits of cmask and the file mode creation 
mask are used. 


RETURN VALUE 

The previous value of the file mode creation mask is returned. 


SEE ALSO 

chmod(2), creat(2), mknod(2), open(2). 

mkdir(l), sh(l) in the ICON/UX User Reference Manual. 


Icon International, Inc. 



UMOUNT (2) 


SYSTEM CALLS 


UMOUNT (2) 


NAME 

umount — unmount a file system 


SYNOPSIS 

int umount (spec) 
char *spec; 


DESCRIPTION 

Umount requests that a previously mounted file system contained on the block spe¬ 
cial device identified by spec be unmounted. Spec is a pointer to a path name. 
After unmounting the file system, the directory upon which the file system was 
mounted reverts to its ordinary interpretation. 

Umount may be invoked only by the super-user. 

Umount will fail if one or more of the following are true: 


jEPERM] 

The process’s effective user ID is not super-user. 

[ENXIO] 

Spec does not exist. 

[ENOTBLKj 

Spec is not a block special device. 

(EINVAL) 

Spec is not mounted. 

[EBUSY] 

A file on spec is busy. 

[EFAULT] 

Spec points to an illegal address. 


RETURN VALUE 

Upon successful completion a value of 0 is returned. Otherwise, a value of —1 is 
returned and errno is set to indicate the error. 


SEE ALSO 

mount(2). 
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NAME 

uname — get name of current UNIX system 


SYNOPSIS 

^include <sys/utsname.h> 

int uname (name) 
struct utsname *name; 


DESCRIPTION 

Uname stores information identifying the current UNIX system in the structure 
pointed to by name. 


Uname uses the structure defined in <sys/utsname.h> whose members are: 


char 

char 

char 

char 

char 


sysname[9 
nodename 
release [9]; 
version [9]; 
machine[9]; 


9 ]; 


Uname returns a null-terminated character string naming the current UNIX system in 
the character array sysname. Similarly, nodename contains the name that the sys¬ 
tem is known by on a communications network. Release and version further identify 
the operating system. Machine contains a standard name that identifies the 
hardware that the UNIX system is running on. 

[EFAULT] Uname will fail if name points to an invalid address. 


RETURN VALUE 

Upon successful completion, a non-negative value is returned. Otherwise, —1 is 
returned and errno is set to indicate the error. 


SEE ALSO 

uname(l) in the ICON/UX User Reference Manual. 
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NAME 

unlink — remove directory entry 


SYNOPSIS 

int unlink (path) 
char *path; 


DESCRIPTION 

Unlink removes the directory entry named by the path name pointed to be path. 

The named file is unlinked unless one or more of the following are true: 

[ENOTDIRj A component of the path prefix is not a directory. 

[ENOENT] The named file does not exist. 

[EACCES] Search permission is denied for a component of the path prefix. 

[EACCES] Write permission is denied on the directory containing the link to be 

removed. 

[EPERM] The named file is a directory and the effective user ID of the process 

is not super-user. 

[EBUSYj The entry to be unlinked is the mount point for a mounted file sys¬ 

tem. 

[ETXTBSY] The entry to be unlinked is the last link to a pure procedure (shared 

text) file that is being executed. 

[EROFS] The directory entry to be unlinked is part of a read-only file system. 

[EFAULT] Path points outside the process’s allocated address space. 


When all links to a file have been removed and no process has the file open, the 
space occupied by the file is freed and the file ceases to exist. If one or more 
processes have the file open when the last link is removed, the removal is postponed 
until all references to the file have been closed. 


RETURN VALUE 

Upon successful completion, a value of 0 is returned. Otherwise, a value of —1 is 
returned and errno is set to indicate the error. 


SEE ALSO 

close(2), link(2), open(2). 

rm(l) in the ICON/UX User Reference Manual. 
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USTAT (2) 


NAME 

ustat — get file system statistics 


SYNOPSIS 

^include <sys/types.li> 
^include <ustat.h> 

int ustat (dev, buf) 
int dev; 

struct ustat *buf; 


DESCRIPTION 

Ustat returns information about a mounted file system. Dev is a device number iden¬ 
tifying a device containing a mounted file system. Buf is a pointer to a ustat struc¬ 
ture that includes to following elements: 


daddr_t f_tfree; 
ino_t f_tinode; 
char f_fname[6]; 

char f_fpack[6]; 


f* Total free blocks */ 

/* Number of free inodes */ 
/* Filsys name */ 

/* Filsys pack name */ 


Ustat will fail if one or more of the following are true: 

[EINVALJ Dev is not the device number of a device containing a mounted file 

system. 

[EFAULT] Buf points outside the process’s allocated address space. 


RETURN VALUE 

Upon successful completion, a value of 0 is returned. Otherwise, a value of —1 is 
returned and errno is set to indicate the error. 


SEE ALSO 

stat(2), fs(4). 
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UTIME (2) 


NAME 

utime — set file access and modification times 


SYNOPSIS 

#include <sys/ty pes Jh> 
int utime (path, times) 
char *path; 
struct utimbuf Himes; 


DESCRIPTION 

Path points to a path name naming a file. Utime sets the access and modification 
times of the named file. 

If times is NULL, the access and modification times of the file are set to the current 
time. A process must be the owner of the file or have write permission to use utime 
in this manner. 

If times is not NULL, times is interpreted as a pointer to a utimbuf structure and the 
access and modification times are set to the values contained in the designated 
structure. Only the owner of the file or the super-user may use utime this way. 

The times in the following structure are measured in seconds since 00:00:00 GMT, 
Jan. 1, 1970. 

struct utimbuf { 

time_t actime; /* access time */ 
time_t modtime; /* modification time */ 

}> 


Utime will fail if one or more of the following are true: 


[ENOENT] 

[ENOTDIR] 

[EACCES] 

[EPERM] 

[EACCES] 


The named file does not exist. 

A component of the path prefix is not a directory. 

Search permission is denied by a component of the path prefix. 

The effective useT ID is not super-user and not the owner of the file 
and times is not NULL 

The effective user ID is not super-user and not the owner of the file 
and times is NULL and write access is denied. 


[EROFS] The file system containing the file is mounted read-only. 

[EFAULT] Times is not NULL and points outside the process’s allocated 

address space. 

[EFAULT] Path points outside the process’s allocated address space. 
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RETURN VALUE 

Upon successful completion, a value of 0 is returned. Otherwise, a value of —1 is 
returned and errno is set to indicate the error. 

SEE ALSO 

stat(2). 
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SYSTEM CALLS 


WAIT (2) 


NAME 

wait — wait for child process to stop or terminate 


SYNOPSIS 

int wait (stat_Ioc) 
int *stat_loc; 

int wait ((int *)0) 


DESCRIPTION 

Wait suspends the calling process until until one of the immediate children ter¬ 
minates or until a child that is being traced stops, because it has hit a break point. 
The wait system call will return prematurely if a signal is received and if a child pro¬ 
cess stopped or terminated prior to the call on wait, return is immediate. 

If statjloc (taken as an integer) is non-zero, 16 bits of information called status are 
stored in the low order 16 bits of the location pointed to by statjoc. Status can be 
used to differentiate between stopped and terminated child processes and if the child 
process terminated, status identifies the cause of termination and passes useful infor¬ 
mation to the parent. This is accomplished in the following manner: 

If the child process stopped, the high order 8 bits of status will contain the 
number of the signal that caused the process to stop and the low order 8 bits 
will be set equal to 0177. 

If the child process terminated due to an exit call, the low order 8 bits of 
status will be zero and the high order 8 bits will contain the low order 8 bits 
of the argument that the child process passed to exit; see exit( 2). 

If the child process terminated due to a signal, the high order 8 bits of status 
will be zero and the low order 8 bits will contain the number of the signal 
that caused the termination. In addition, if the low’ order seventh bit (i.e., bit 
200) is set, a “core image” will have been produced; see signal(2). 

If a parent process terminates without waiting for its child processes to terminate, 
the parent process ID of each child process is set to 1. This means the initialization 
process inherits the child processes; see intro(2). 

Wait will fail and return immediately if one or more of the following are true: 

[ECHILD] The calling process has no existing unwaited-for child processes. 

[EFAULT] Statjioc points to an illegal address. 

RETURN VALUE 

If wait returns due to the receipt of a signal, a value of —1 is returned to the calling 
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SYSTEM CALLS 


WAIT (2) 


process and errno is set to EINTR. If wait returns due to a stopped or terminated 
child process, the process ID of the child is returned to the calling process. Other¬ 
wise, a value of —1 is returned and errno is set to indicate the error. 


SEE ALSO 

exec(2), exit(2), fork(2), intro(2), pause(2), ptrace(2), signal(2). 


WARNING 

See WARNING in $ignal{2). 
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SYSTEM CALLS 


WRITE (2) 


NAME 

write — write on a file 



SYNOPSIS 

int write (fildes, buf, nbyte) 
int fildes; 
char *buf; 
unsigned nbyte; 


DESCRIPTION 

Fildes is a file descriptor obtained from a creat, open, dup, fcntl, or pipe system call. 

Write attempts to write nbyte bytes from the buffer pointed to by buf to the file 
associated with the fildes. 

On devices capable of seeking, the actual writing of data proceeds from the position 
in the file indicated by the file pointer. Upon return from write, the file pointer is 
incremented by the number of bytes actually written. 

On devices incapable of seeking, writing always takes place starting at the current 
position. The value of a file pointer associated with such a device is undefined. 

If the 0_APPEND flag of the file status flags is set, the file pointer will be set to the 
end of the file prior to each write. 

Write will fail and the file pointer will remain unchanged if one or more of the fol¬ 
lowing are true: 

[EBADF] Fildes is not a valid file descriptor open for writing. 

[EPIPE and SIGPIPE signal] 

An attempt is made to write to a pipe that is not open for reading 
by any process. 

An attempt was made to write a file that exceeds the process’s file 
size limit or the maximum file size. See ulimit{ 2). 

Buf points outside the process’s allocated address space. 

A signal was caught during the write system call. 


[EFBIG] 

[EFAULT] 

[E1NTR] 


If a write requests that more bytes be written than there is room for (e.g., the ulimit 
(see ulimit(2)) or the physical end of a medium), only as many bytes as there is room 
for will be written. For example, suppose there is space for 20 bytes more in a file 
before reaching a limit. A write of 512 bytes will return 20. The next write of a 
non-zero number of bytes will give a failure return (except as noted below). 
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If the file being written is a pipe (or FIFO) and the 0_NDELAY flag of the file flag word 
is set, then write to a full pipe (or FIFO) will return a count of 0. Otherwise 
(0_NDELAY clear), writes to a full pipe (or FIFO) will block until space becomes avail¬ 
able. 


RETURN VALUE 

Upon successful completion the number of bytes actually written is returned. Other¬ 
wise, —1 is returned and errno is set to indicate the error. 


SEE ALSO 

creat(2), dup(2), lseek(2), open(2), pipe(2), ulimit(2). 


Inc. 
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INTRO (3) 


NAME 

intro — introduction to subroutines and libraries 


SYNOPSIS 

^include <stdio.h> 

^include <math.h> 


DESCRIPTION 

This section describes functions found in various libraries, other than those functions 
that directly invoke ICON/UXV system primitives, which are described in Section 2 of 
this volume. Certain major collections are identified by a letter after the section 
number: 

(3C) These functions, together with those of Section 2 and those marked (3S), con¬ 
stitute the Standard C Library libc, which is automatically loaded by the C 
compiler, cc(l). The link editor ld( 1) searches this library under the — lc 
option. Declarations for some of these functions may be obtained from 
#include files indicated on the appropriate pages. 

(3S) These functions constitute the “standard I/O package” [see stdio( 3S)|. These 
functions are in the library libc, already mentioned. Declarations for these 
functions may be obtained from the ^include file <stdio.h>. 

(3M) These functions constitute the Math Library, libm. They are automatically 
accessed by the F77 compiler to implement the intrinsic math functions 
described in section 3F. They are not automatically loaded by the C com¬ 
piler, cc(l); however, the link editor searches this library under the —lm 
option. Declarations for these functions may be obtained from the ^include 
file <math.h>. Several generally useful mathematical constants are also 
defined there [see math( 5)]. 

(3X) Various specialized libraries. The files in which these libraries are found are 
given on the appropriate pages. 

(3F) These functions constitute the F77 intrinsic functions library, UbF7 7, which 
includes the standard FORTRAN intrinsic functions as a subset. These func¬ 
tions are automatically available to the FORTRAN programmer and require no 
special invocation of the compiler. 


DEFINITIONS 

A character is any bit pattern able to fit into a byte on the machine. The null 
character is a character with value 0, represented in the C language as ’\0’. A char¬ 
acter array is a sequence of characters. A null-terminated character array is a 
sequence of characters, the last of which is the null character. A string is a designa¬ 
tion for a null-terminated character array. The null string is a character array con¬ 
taining only the null character. A NULL pointer is the value that is obtained by 
casting 0 into a pointer. The C language guarantees that this value will not match 
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INTRO (3) 


that of any legitimate pointer, so many functions that return pointers return it to 
indicate an error. NULL is defined as 0 in <stdio.h>; the user can include an 
appropriate definition if not using <stdio.h>. 

Many groups of FORTRAN intrinsic functions have generic function names that do not 
require explicit or implicit type declaration. The type of the function will be deter¬ 
mined by the type of its argument(s). For example, the generic function max will 
return an integer value if given integer arguments ( maxO ), a real value if given real 
arguments ( amaxl ), or a double-precision value if given double-precision arguments 
(dmaxl). 


FILES 


/lib/libc.a 

/lib/libm.a 

/usr/lib/libF77.a 


SEE ALSO 

intro(2), stdio(3S), math(5). 

ar(l), cc(l), 177(1), ld(l), lint(l), nm(l) in the ICON/UXV User Reference Manual. 


DIAGNOSTICS 

Functions in the C and Math Libraries (3C and 3M) may return the conventional 
values 0 or ±HUGE (the largest-magnitude single-precision floating-point numbers; 
HUGE is defined in the <math.h> header file) when the function is undefined for the 
given arguments or when the value is not representable. In these cases, the external 
variable errno [see intro( 2)j is set to the value EDOM or ERANGE. As many of the FOR¬ 
TRAN intrinsic functions use the routines found in the Math Library, the same con¬ 
ventions apply. 


WARNING 

Many of the functions in the libraries call and/or refer to other functions and exter¬ 
nal variables described in this section and in section 2 ( System Calls). If a program 
inadvertantly defines a function or external variable with the same name, the 
presumed library version of the function or external variable may not be loaded. 
The lint(l) program checker reports name conflicts of this kind as “multiple declara¬ 
tions” of the names in question. Definitions for sections 2, 3C, and 3S are checked 
automatically. Other definitions can be included by using the —1 option (for example, 
—1m includes definitions for the Math Library, section 3M). Use of lint is highly 
recommended. 
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COMPATIBILITY ROUTINES 


A64L (3C) 


NAME 

a64l, 164a — convert between long integer and base-64 ASCII string 


SYNOPSIS 

long &641 (s) 
char *s; 

char *164a (1) 
long 1; 


DESCRIPTION 

These functions are used to maintain numbers stored in base-64 ASCII characters. 
This is a notation by which long integers can be represented by up to six characters; 
each character represents a “digit” in a radix-64 notation. 

The characters used to represent “digits” are . for 0, / for 1 , 0 through 9 for 2—11, 
A through Z for 12—37, and a through z for 38—63. 

A 64 I takes a pointer to a null-terminated base-64 representation and returns a 
corresponding long value. If the string pointed to by s contains more than six char¬ 
acters, a 64 l will use the first six. 

L64a takes a long argument and returns a pointer to the corresponding base-64 
representation. If the argument is 0, 164a returns a pointer to a null string. 


BUGS 


The value returned by 164a is a pointer into a static buffer, the contents of which are 
overwritten by each call. 


Icon International, Inc. 


1 



ABORT (3C) 


COMPATIBILITY ROUTINES 
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NAME f } 

'< - 

abort — generate an IOT fault 


SYNOPSIS 

int abort ( ) 


DESCRIPTION 

Abort first closes all open files if possible, then causes an IOT signal to be sent to the 
process. This usually results in termination with a core dump. 

It is possible for abort to return control if SIGIOT is caught or ignored, in which case 
the value returned is that of the kill{2) system call. 


SEE ALSO 

exit(2), kill(2), signal(2). 

adb(l), sdb(l) in the ICON/UXV User Reference Manual. 


DIAGNOSTICS 

If SIGIOT is neither caught nor ignored, and the current directory is writable, a core 
dump is produced and the message “abort — core dumped” is written by the shell. 
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( 


NAME 

abs — return integer absolute value 


SYNOPSIS 

int abs (i) 
int i; 

DESCRIPTION 

Abs returns the absolute value of its integer operand. 


BUGS 


In two’s-complement representation, the absolute value of the negative integer with 
largest magnitude is undefined. Some implementations trap this error, but others 
simply ignore it. 


( 


SEE ALSO 

floor(3M). 
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NAME 

bsearch — binary search a sorted table 


SYNOPSIS 

^include <search.h> 

char *bsearch ((char *) key, (char *) base, nel, sizeof (*key), compar) 
unsigned nel; 
int (*compar)( ); 


DESCRIPTION 

Bsearch is a binary search routine generalized from Ivnuth (6.2.1) Algorithm B. It 
returns a pointer into a table indicating where a datum may be found. The table 
must be previously sorted in increasing order according to a provided comparison 
function. Key points to a datum instance to be sought in the table. Base points to 
the element at the base of the table. Nel is the number of elements in the table. 
Compar is the name of the comparison function, which is called with two arguments 
that point to the elements being compared. The function must return an integer less 
than, equal to, or greater than zero as accordinly the first argument is to be con¬ 
sidered less than, equal to, or greater than the second. 


EXAMPLE 

The example below searches a table containing pointers to nodes consisting of a 
string and its length. The table is ordered alphabetically on the string in the node 
pointed to by each entry. 

This code fragment reads in strings and either finds the corresponding node and 
prints out the string and its length, or prints an error message. 


^include <stdio.h> 
^include <search.h> 


#define TABSIZE 1000 


struct node { 

char ^string; 
int length; 


}; 

struct node table [TABSIZE]; 


/* 


/* 


these are stored in the table 


table to be searched */ 


*/ 


{ 
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struct node *node_ptr, node; 

int node_compare( ); /* routine to compare 2 nodes */ 

char str_space[20]; /* space to read string into */ 


node.string = str_space; 

while (scanf("%s", node.string) != EOF) { 

node_ptr = (struct node *)bsearch((char *)(&node), 
(char *)table, TABSIZE, 
sizeof(struct node), node_compare); 
if (node_ptr != NULL) { 

(void)printf("string = %20s, length = %d\n", 
node_ptr—>string, node_ptr—>length); 

} else { 

(void)printf("not found: %s\n", node.string); 

, 1 5 

/* 

This routine compares two nodes based on an 
alphabetical ordering of the string field. 

*/ 

int 

node_compare(nodel, node2) 
struct node *nodcl, *node2; 

{ 

return strcmp(nodel—>string, node2—>string); 


NOTES 

The pointers to the key and the element at the base of the table should be of 
type pointer-to-element, and cast to type pointer-to-character. 

The comparison function need not compare every byte, so arbitrary data may 
be contained in the elements in addition to the values being compared. 

Although declared as type pointer-to-character, the value returned should be 
cast into type pointer-to-element. 


SEE ALSO 

hsearch(3C), lsearch(3C), qsort(3C), tsearch(3C). 

DIAGNOSTICS 

A NULL pointer is returned if the key cannot be found in the table. 
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NAME 

clock — report CPU time used 


SYNOPSIS 

long clock ( ) 


DESCRIPTION 

Clock returns the amount of CPU time (in microseconds) used since the first call to 
clock. The time reported is the sum of the user and system times of the calling pro¬ 
cess and its terminated child processes for which it has executed wait( 2) or 
$ystem(ZS). 

The resolution of the clock is 20 milliseconds on ICON products, 10 milliseconds on 
AT&T Technologies 3B computer processors, 16.667 milliseconds on Digital Equip¬ 
ment Corporation processors. 


SEE ALSO 

times(2), wait(2), system(3S). 


BUGS 


The value returned by clock is defined in microseconds for compatibility with sys¬ 
tems that have CPU clocks with much higher resolution. Because of this, the value 
returned will wrap around after accumulating only 2147 seconds of CPU time (about 
36 minutes). 


\ 
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NAME 

toupper, tolower, _toupper, _tolower, toascii — translate characters 


SYNOPSIS 

#include <ctype.h> 

int toupper (c) 
int c; 

int tolower (c) 
int c; 

int _toupper (c) 
int c; 

int _tolower (c) 
int c; 

int toascii (c) 
int c; 


DESCRIPTION 

Toupper and tolower have as domain the range of getc( 3S): the integers from —1 
through 255. If the argument of toupper represents a lower-case letter, the result is 
the corresponding upper-case letter. If the argument of tolower represents an upper¬ 
case letter, the result is the corresponding lower-case letter. All other arguments in 
the domain are returned unchanged. 

The macros _toupper and _ tolower , are macros that accomplish the same thing as 
toupper and tolower but have restricted domains and are faster. Jtoupper requires a 
lower-case letter as its argument; its result is the corresponding upper-case letter. 
The macro _ tolower requires an upper-case letter as its argument; its result is the 
corresponding lower-case letter. Arguments outside the domain cause undefined 
results. 

Toascii yields its argument with all bits turned off that are not part of a standard 
ASCII character; it is intended for compatibility with other systems. 


SEE ALSO 

ctype(3C), getc(3S). 
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END (3C) 


NAME 

end, etext, edata — last locations in program 


SYNOPSIS 

extern end; 
extern etext; 
extern edata; 


DESCRIPTION 

These names refer neither to routines nor to locations with interesting contents. The 
address of etext is the first address above the program text, edata above the initial¬ 
ized data region, and end above the uninitialized data region. 

When execution begins, the program break (the first location beyond the data) coin¬ 
cides with end, but the program break may be reset by the routines of brk( 2), 
malloc( 3C), standard input/output (stdio( 3S)), the profile (—p) option of cc(l), and so 
on. Thus, the current value of the program break should be determined by sbrk(O) 
(see brk(2)). 


SEE ALSO 

brk(2), malloc(3C), stdio(3S). 

cc(l) in the ICON/UXV User Reference Manual. 
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NAME 

crypt, setkey, encrypt — generate DES encryption 


SYNOPSIS 

char *crypt (key, salt) 
char *key, *salt; 

void setkey (key) 
char *key; 

void encrypt (block, edflag) 
char *block; 
int edflag; 


DESCRIPTION 

Crypt is the password encryption function. It is based on the NBS Data Encryption 
Standard (DES), with variations intended (among other things) to frustrate use of 
hardware implementations of the DES for key search. 

Key is a user’s typed password. Salt is a two-character string chosen from the set 
[a-zA-ZO-9./]; this string is used to perturb the DES algorithm in one of 4096 
different w'ays, after which the password is used as the key to encrypt repeatedly a 
constant string. The returned value points to the encrypted password. The first two 
characters are the salt itself. 


The setkey and encrypt entries provide (rather primitive) access to the actual DES 
algorithm. The argument of setkey is a character array of length 64 containing only 
the characters with numerical value 0 and 1. If this string is divided into groups of 
8, the low-order bit in each group is ignored; this gives a 56-bit key which is set into 
the machine. This is the key that will be used with the above mentioned algorithm 
to encrypt or decrypt the string block with the function encrypt. 

The argument to the encrypt entry is a character array of length 64 containing only 
the characters with numerical value 0 and 1. The argument array is modified in 
place to a similar array representing the bits of the argument after having been sub¬ 
jected to the DES algorithm using the key set by setkey. If edflag is zero, the argu¬ 
ment is encrypted; if non-zero, it is decrypted. 

SEE ALSO 

getpass(3C), passwd(4). 

login(l), passwd(l) in the ICON/UXV User Reference Manual. 
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BUGS 

The return value points to static data that are overwritten by each call. 
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NAME 

ctime, localtime, gmtime, asctime, tzset — convert date and time to string 


SYNOPSIS 

#include <time.h> 

char *ctime (clock) 
long *clock; 

struct tm *localtime (clock) 
long *clock; 

struct tm *gmtime (clock) 
long *clock; 

char *asctime (tm) 
struct tm *tm; 

extern long timezone; 

extern int daylight; 

extern char *tzname[2]; 

void tzset ( ) 


DESCRIPTION 

Ctime converts a long integer, pointed to by clock, representing the time in seconds 
since 00:00:00 GMT, January 1, 1970, and returns a pointer to a 26-character string 
in the following form. All the fields have constant width. 

Sun Sep 16 01:03:52 1973\n\0 


Localtime and gmtime return pointers to “tm” structures, described below. Local¬ 
time corrects for the time zone and possible Daylight Savings Time; gmtime converts 
directly to Greenwich Mean Time (GMT), which is the time the UNIX system uses. 

Asctime converts a “tm” structure to a 26-character string, as shown in the above 
example, and returns a pointer to the string. 
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Declarations of all the functions and externals, and the “tin” structure, are in the 
<time.h> header file. The structure declaration is: 


struct tm { 

int tm_sec; 
int tm_min; 
int tm_hour; 
int tm_mday; 
int tm_mon; 
int tm_year; 
int tm_wday; 
int tm_yday; 
int tm_isdst; 

}; 


/* seconds (0 - 59) */ 

/* minutes (0 - 59) */ 

/* hours (0 - 23) */ 

/* day of month (1 - 31) */ 

/* month of year (0 - 11) */ 
/* year — 1900 */ 

/* day of week (Sunday = 0) */ 

/* day of year (0 - 365) */ 


Tm_isdst is non-zero if Daylight Savings Time is in effect. 

The external long variable timezone contains the difference, in seconds, between 
GMT and local standard time (in EST, timezone is 5*60*60); the external variable 
daylight is non-zero if and only if the standard U S A. Daylight Savings Time conver¬ 
sion should be applied. The program knows about the peculiarities of this conversion 
in 1974 and 1975; if necessary, a table for these years can be extended. 

If an environment variable named TZ is present, asctime uses the contents of the 
variable to override the default time zone. The value of TZ must be a three-letter 
time zone name, followed by a number representing the difference between local time 
and Greenwich Mean Time in hours, followed by an optional three-letter name for a 
daylight time zone. For example, the setting for New Jersey would be EST5EDT 
The effects of setting TZ are thus to change the values of the external variables 
timezone and daylight ; in addition, the time zone names contained in the external 
variable 

char *tzname[2] = { "EST", "EDT" }; 

are set from the environment variable TZ The function tzsei sets these external 
variables from TZ; tzset is called by asctime and may also be called explicitly by the 
user. 

Note that in most installations, TZ is set by default when the user logs on, to a value 
in the local /etc/profile file (see profile^ 4)). 

SEE ALSO 

time(2), getenv(3C), profile(4), environ(5). 
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BUGS 


The return values point to static data whose content is overwritten by each call. 
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NAME 

isalpha, isupper, islower, isdigit, isxdigit, isalnum, isspace, ispunct, isprint, isgraph, 
iscntrl, isascii — classify characters 


SYNOPSIS 

^include <ctype.h> 

int isalpha (c) 
int c; 


DESCRIPTION 


These macros classify character-coded integer values by table lookup. Each is a 
predicate returning nonzero for true, zero for false. Isascii is defined on all integer 
values; the rest are defined only where isascii is true and on the single non-ASCII 
value EOF (—1 — see stdio{ 3S)). 

isalpha c is a letter. 

isupper c is an upper-case letter. 

islower c is a lower-case letter. 


isdigit 

isxdigit 

isalnum 

isspace 


c is a digit [0-9]. 

c is a hexadecimal digit [0-9], [A-F] or [a-f]. 
c is an alphanumeric (letter or digit). 

c is a space, tab, carriage return, new-line, vertical tab, or form¬ 
feed. 


ispunct 

isprint 

isgraph 

iscntrl 

isascii 


c is a punctuation character (neither control nor alphanumeric), 
c is a printing character, code 040 (space) through 0176 (tilde), 
c is a printing character, like isprint except false for space. 

c is a delete character (0177) or an ordinary control character (less 
than 040). 

c is an ASCII character, code less than 0200. 


DIAGNOSTICS 

If the argument to any of these macros is not in the domain of the function, the 
result is undefined. 
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SEE ALSO 

stdio(3S), ascii(5). 
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NAME 

dial — establish an out-going terminal lme connection 


SYNOPSIS 

#include <dial.h> 

int dial (call) 

CALL call; 

void undial (fd) 
int fd; 


DESCRIPTION 

Dial returns a file-descriptor for a terminal line open for read/write. The argument 
to dial is a CALL structure (defined in the <dial.h> header file). When finished with 
the terminal line, the calling program must invoke undial to release the semaphore 
that has been set during the allocation of the terminal device. 

The definition of CALL in the <dial.h> header file is: 

typedef struct { 


struct termio *attr; 

/♦ pointer to termio attribute struct ♦/ 

int 

baud; 

/♦ transmission data rate ♦/ 

int 

speed; 

/♦ 212A modem: low=300, high=1200 ♦/ 

char 

♦line; 

/♦ device name for out-going line ♦/ 

char 

♦telno; 

/♦ pointer to tel-no digits string */ 

int 

modem; 

/♦ specify modem control for direct lines ♦/ 

char 

♦device; 

/♦Will hald the name of the device used 



to make a connection ♦/ 

int 

dev_]en; 

/♦ The length of the device used to make connection ♦/ 


} CALL; 

The CALL element speed is intended only for use with an outgoing dialed call, in 
which case its value should be either 300 or 1200 to identify the 113A modem, or the 
high- or low-speed setting on the 212A modem. Note that the 113A modem or the 
low-speed setting of the 212A modem will transmit at any rate between 0 and 300 
bits per second. However, the high-speed setting of the 212A modem transmits and 
receivers at 1200 bits per secound only. The CALL element baud is for the desired 
transmission baud rate. For example, one might set baud to 110 and speed to 300 
(or 1200). However, if speed set to 1200 baud must be set to high (1200). If the 
desired terminal line is a direct line, a string pointer to its device-name should be 
placed in the line element in the CALL structure. Legal values for such terminal 
device names are kept in the L-devices file. In this case, the value of the baud ele¬ 
ment need not be specified as it will be determined from the L-devices file. The telno 
element is for a pointer to a character string representing the telephone number to 
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be dialed. Such numbers may consist only of symbols described on the ocu(7). The 
termination symbol will be supplied by the dial function, and should not be included 
in the telno string passed to dial in the CALL structure. The CALL element modem 
is used to specify modem control for direct lines. This element should be non-zero if 
modem control is required. The CALL element attr is a pointer to a termio struc¬ 
ture, as defined in the termio.h header file. A NULL value for this pointer element 
may be passed to the dial function, but if such a structure is included, the elements 
specified in it will be set for the outgoing terminal line before the connection is esta¬ 
blished. This is often important for certain attributes such as parity and baud-rate. 

The CALL element device is used to hold the device name (cul..) that establishes the 
connection. 

The CALL element devjlen is the length of the device name that is copied into the 
array device. 


FILES 


/usr/lib/uucp/L-devices 
/usr/spool/uucp/LCK..t<y- device 


SEE ALSO 

uucp(lC) in the ICON/UXV User Reference Manual. 
alarm(2), read(2), write(2). 

acu(7), termio(7) in the UNIX System Administrator Reference Manual. 


DIAGNOSTICS 


On failure, a negative value indicating the reason for the failure will be returned. 
Mnemonics for these negative indices as listed here are defined in the <dial.li> 
header file. 


ENTRPT 

-1 

D_HUNG 

-2 

NO_ANS 

-3 

ILLJBD 

-4 

AJPROB 

-5 

LJPROB 

—6 

NO_Ldv 

-7 

DV_NT_A 

—8 

DV_NT_K 

-9 

NO_BD_A 

-10 

NO_BD_K 

-11 


/* interrupt occurred */ 

/* dialer hung (no return from write) */ 

/* no answer within 10 seconds */ 

/* illegal baud-rate */ 

/* acu problem (open() failure) */ 

/* line problem (open() failure) */ 

/* can’t open LDEVS file */ 

/* requested device not available */ 

/* requested device not known */ 

/* no device available at requested baud */ 
/* no device known at requested baud */ 
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WARNINGS 

Including the <dial.h> header file automatically includes the <termio.h> header 
file. 

The above routine uses <stdio.h>, which causes it to increase the size of programs, 
not otherwise using standard I/O, more than might be expected. 


BUGS 


An alarm( 2) system call for 3600 seconds is made (and caught) within the dial 
module for the purpose of “touching” the LCK.. file and constitutes the device alloca¬ 
tion semaphore for the terminal device. Otherwise, uucp(lC) may simply delete the 
LCK.. entry on its 90-minute clean-up rounds. The alarm may go off while the user 
program is in a read( 2) or write(2) system call, causing an apparent error return. If 
the user program expects to be around for an hour or more, error returns from reads 
should be checked for (errno==EINTR), and the read possibly reissued. 
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NAME 

drand48, erand48, lrand48, nrand48, mrand48, jrand48, srand48, seed48, lcong48 — 
generate uniformly distributed pseudo-random numbers 


SYNOPSIS 

double drand48 ( ) 

double erand48 (xsubi) 
unsigned short xsubi [3]; 

long lrand48 ( ) 

long nrand48 (xsubi) 
unsigned short xsubi[3]; 

long mrand48 ( ) 

long jrand48 (xsubi) 
unsigned short xsubi [3]; 

void srand48 (seedval) 
long seedval; 

unsigned short *seed48 (seedlBv) 
unsigned short seedl6v[3]; 

void lcong48 (param) 
unsigned short param [7]; 


DESCRIPTION 

This family of functions generates pseudo-random numbers using the well-known 
linear congruential algorithm and 48-bit integer arithmetic. 


Functions drand48 and erand48 return non-negative double-precision floating-point 
values uniformly distributed over the interval [0.0, 1.0). 


Functions lrand48 and nrand48 return non-negative long integers uniformly distri¬ 
buted over the interval [0, 2 31 ). 

Functions mrand48 and jrand48 return signed long integers uniformly distributed 
over the interval [—2 31 , 2 31 ). 
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Functions srand48, seed48 and lcong48 are initialization entry points, one of which 
should be invoked before either drand48, lrand48 or mrand48 is called. (Although it 
is not recommended practice, constant default initializer values will be supplied 
automatically if drand48, lrand48 or mrand48 is called without a prior call to an ini¬ 
tialization entry point.) Functions erand48, nrand48 and jrand48 do not require an 
initialization entry point to be called first. 

All the routines work by generating a sequence of 48-bit integer values, X it according 
to the linear congruential formula 

— (aY, + c ) mo d m «>0. 

The parameter m=2 48 ; hence 48-bit integer arithmetic is performed. Unless lcong48 
has been invoked, the multiplier value a and the addend value c are given by 

a m 5DEECE66D 1S = 273673163155 8 
c = B|j = 13 g. 



The value returned by any of the functions drand48, erand48, lrand48, nrand48, 
mrand48 or jrand48 is computed by first generating the next 48-bit X { in the 
sequence. Then the appropriate number of bits, according to the type of data item 
to be returned, are copied from the high-order (leftmost) bits of Y| and transformed 
into the returned value. 

The functions drand48, lrand48 and mrand48 store the last 48-bit X ( generated in an 
internal buffer; that is why they must be initialized prior to being invoked. The 
functions erand48, nrand48 and jrand48 require the calling program to provide 
storage for the successive X { values in the array specified as an argument when the 
functions are invoked. That is why these routines do not have to be initialized; the 
calling program merely has to place the desired initial value of X { into the array and 
pass it as an argument. By using different arguments, functions erand48, nr and 4 8 
and jrand48 allow separate modules of a large program to generate several indepen¬ 
dent streams of pseudo-random numbers, i.e., the sequence of numbers in each 
stream will not depend upon how many times the routines have been called to gen¬ 
erate numbers for the other streams. 

The initializer function srand48 sets the high-order 32 bits of X { to the 32 bits con¬ 
tained in its argument. The low-order 16 bits of X { are set to the arbitrary value 
330E 18 . 


The initializer function seed48 sets the value of X { to the 48-bit value specified in the 
argument array. In addition, the previous value of Yj is copied into a 48-bit internal 
buffer, used only by seed48, and a pointer to this buffer is the value returned by 
seed48. This returned pointer, which can just be ignored if not needed, is useful if a 
program is to be restarted from a given point at some future time — use the pointer 
to get at and store the last Y,- value, and then use this value to reinitialize via 
seed48 when the program is restarted. 

'w 
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The initialization function lcong48 allows the user to specify the initial Xi, the multi¬ 
plier value a, and the addend value e. Argument array elements param[0-2] specify 
X{, paramfS-5 / specify the multiplier a, and param[6j specifies the 16-bit addend c. 
After lcong48 has been called, a subsequent call to either srand48 or seed48 will 
restore the “standard” multiplier and addend values, a and c, specified on the previ¬ 
ous page. 


NOTES 

The versions of these routines for the VAX-11 and PDP-11 are coded in assembly 
language for maximum speed. It requires approximately 80 /isec on a VAX-11/780 
and 130 nsec on a PDP-ll/70 to generate one pseudo-random number. On other 
computers, the routines are coded in portable C. The source code for the portable 
version can even be used on computers which do not have floating-point arithmetic. 
In such a situation, functions drand48 and erand48 do not exist; instead, they are 
replaced by the two new functions below. 

long irand48 (m) 
unsigned short m; 

long krand48 (xsubi, m) 
unsigned short xsubi[3], m; 

Functions irand48 and krand48 return non-negative long integers uniformly distri¬ 
buted over the interval [0, m—l]. 


SEE ALSO 

rand(3C). 
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NAME l , 

x. 

ecvt, fcvt, gcvt — convert floating-point number to string 


SYNOPSIS 

char *ecvt (value, ndigit, decpt, sign) 

double value; 

int ndigit, *decpt, *sign; 

char *fcvt (value, ndigit, decpt, sign) 

double value; 

int ndigit, *decpt, *sign; 

char *gcvt (value, ndigit, buf) 
double value; 
int ndigit; 
char *buf; 


DESCRIPTION 

Ecvt converts value to a null-terminated string of ndigit digits and returns a pointer 
thereto. The high-order digit is non-zero, unless the value is zero. The low-order 
digit is rounded. The position of the decimal point relative to the beginning of the 
string is stored indirectly through decpt (negative means to the left of the returned 
digits). The decimal point is not included in the returned string. If the sign of the 
result is negative, the word pointed to by sign is non-zero, otherwise it is zero. 

Fcvt is identical to ecvt, except that the correct digit has been rounded for printf 
“%f” (FORTRAN F-format) output of the number of digits specified by ndigit. 

Gcvt converts the value to a null-terminated string in the array pointed to by buf 
and returns buf. It attempts to produce ndigit significant digits in FORTRAN F- 
format if possible, otherwise E-format, ready for printing. A minus sign, if there is 
one, or a decimal point will be included as part of the returned string. Trailing zeros 
are suppressed. 


SEE ALSO 

printf(3S). 


BUGS 


The values returned by ecvt and fcvt point to a single static data array w’hose con¬ 
tent is overwritten by each call. 

A 

I 

\ 
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NAME 

end, etext, edata — last locations in program 


SYNOPSIS 

extern end; 
extern etext; 
extern edata; 


DESCRIPTION 

These names refer neither to routines nor to locations with interesting contents. The 
address of etext is the first address above the program text, edata above the initial¬ 
ized data region, and end above the uninitialized data region. 

When execution begins, the program break (the first location beyond the data) coin¬ 
cides with end, but the program break may be reset by the routines of brk(2), 
malloc(3C), standard input/output (stdio( 3S)), the profile (—p) option of cc(l), and so 
on. Thus, the current value of the program break should be determined by sbrk(O) 
(see brk( 2)). 


SEE ALSO 

brk(2), malloc(3C), stdio(3S). 

cc(l) in the ICON/UXV User Reference Manual. 
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NAME 

frexp, Idexp, modf — manipulate parts of floating-point numbers 


SYNOPSIS 

double frexp (value, eptr) 
double value; 
int *eptr; 

double Idexp (value, exp) 
double value; 
int exp; 

double modf (value, iptr) 
double value, *iptr; 


DESCRIPTION 

Every non-zero number can be written uniquely as x* 2 n , where the “mantissa” 
(fraction) x is in the range 0.5 < ja:j < 1.0, and the “exponent” n is an integer. 
Frexp returns the mantissa of a double value , and stores the exponent indirectly in 
the location pointed to by eptr. If value is zero, both results returned by frexp are 
zero. 

Ldexp returns the quantity value* 2 ezp . 

Modf returns the signed fractional part of value and stores the integral part 
indirectly in the location pointed to by iptr. 


DIAGNOSTICS 

If Idexp would cause overflow, ±HUGE is returned (according to the sign of value), 
and errno is set to ERANGE. 

If Idexp would cause underflow, zero is returned and errno is set to ERANGE. 
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NAME 

ftw — walk a file tree 


SYNOPSIS 

^include <ftw.h> 

int ftw (path, fn, depth) 
char *path; 
int (*fn) ( ); 
int depth; 


DESCRIPTION 

Ftw recursively descends the directory hierarchy rooted in path. For each object in 
the hierarchy, ftw calls fn, passing it a pointer to a null-terminated character string 
containing the name of the object, a pointer to a stat structure (see stat( 2)) contain¬ 
ing information about the object, and an integer. Possible values of the integer, 
defined in the <ftw.h> header file, are FTWJF for a file, FTW_D for a directory, 
FTWJDNR for a directory that cannot be read, and FTW_NS for an object for which 
stat could not successfully be executed. If the integer is FTW_DNR, descendants of 
that directory will not be processed. If the integer is FTW_NS, the stat structure 
will contain garbage. An example of an object that would cause FTW_NS to be 
passed to fn would be a file in a directory with read but without execute (search) 
permission. 

Ftw visits a directory before visiting any of its descendants. 

The tree traversal continues until the tree is exhausted, an invocation of fn returns a 
nonzero value, or some error is detected within ftw (such as an I/O error). If the 
tree is exhausted, ftw returns zero. If fn returns a nonzero value, ftw stops its tree 
traversal and returns whatever value was returned by fn. If ftw detects an error, it 
returns —1, and sets the error type in errno. 

Ftw uses one file descriptor for each level in the tree. The depth argument limits the 
number of file descriptors so used. If depth is zero or negative, the effect is the same 
as if it were 1 . Depth must not be greater than the number of file descriptors 
currently available for use. Ftw will run more quickly if depth is at least as large as 
the number of levels in the tree. 


SEE ALSO 

stat(2), malloc(3C). 
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BUGS 


Because ftw is recursive, it is possible for it to terminate with a memory fault when 
applied to very deep file structures. 

It could be made to run faster and use less storage on deep structures at the cost of 
considerable complexity. 

Ftw uses malloc{ 3C) to allocate dynamic storage during its operation. If ftw is forci¬ 
bly terminated, such as by longjmp being executed by fn or an interrupt routine, ftw 
will not have a chance to free that storage, so it will remain permanently allocated. 
A safe way to handle interrupts is to store the fact that an interrupt has occurred, 
and arrange to have fn return a nonzero value at its next invocation. 
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NAME 

getcwd — get path-name of current working directory 


SYNOPSIS 

char *getcwd (buf, size) 
char *buf; 
int size; 


DESCRIPTION 

Getcwd. returns a pointer to the current directory path-name. The value of size 
must be at least two greater than the length of the path-name to be returned. 

If buf is a NULL pointer, getcwd will obtain size bytes of space using malloc( 3C). In 
this case, the pointer returned by getcwd may be used as the argument in a subse¬ 
quent call to free. 

The function is implemented by using popen{ 3S) to pipe the output of the ptcrf(l) 
command into the specified string space. 


EXAMPLE 


char *cwd, *getcwd(); 


if ((cwd = getcwd((char *)NULL, 64)) == NULL) { 

perror(“pwd”); 

exit(l); 


printf(“%s\n”, cwd); 


SEE ALSO 

malloc(3C), popen(3S). 

pwd(l) in the ICON/UXV User Reference Manual. 


DIAGNOSTICS 

Returns NULL with errno set if size is not large enough, or if an error ocurrs in a 
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lower-level function. 



4 —\ 
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NAME 

getenv — return value for environment name 


SYNOPSIS 

char *getenv (name) 
char *name; 


DESCRIPTION 

Getenv searches the environment list (see environ( 5)) for a string of the form 
name=value, and returns a pointer to the value in the current environment if such a 
string is present, otherwise a NULL pointer. 


SEE ALSO 

exec(2), putenv(3C), environ(5). 
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NAME 

getgrent, getgrgid, getgrnam, setgrent, endgrent, fgetgrent — get group file entry 

SYNOPSIS 

#include <grp.h> 

struct group *getgrent ( ) 

struct group *getgrgid (gid) 
int gid; 

struct group *getgrnam (name) 
char *name; 

void setgrent ( ) 

void endgrent ( ) 

struct group *fgetgrent (f) 

FILE *f; 


DESCRIPTION 

Getgrent, getgrgid and getgrnam each return pointers to an object with the following 
structure containing the broken-out fields of a line in the /etc/group file. Each line 
contains a “group” structure, defined in the <grp.h> header file. 


struct group { 

char *gr_name; 
char *gr_passwd; 

int gr gid; 

char **gr_mem; 


/* the name of the group */ 

/* the encrypted group password */ 

/* the numerical group ID */ 

/* vector of pointers to member names */ 


Getgrent when first called returns a pointer to the first group structure in the file; 
thereafter, it returns a pointer to the next group structure in the file; so, successive 
calls may be used to search the entire file. Getgrgid searches from the beginning of 
the file until a numerical group id matching gid is found and returns a pointer to the 
particular structure in which it was found. Getgrnam searches from the beginning of 
the file until a group name matching name is found and returns a pointer to the par¬ 
ticular structure in which it was found. If an end-of-file or an error is encountered 
on reading, these functions return a NULL pointer. 
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A call to setgrent has the effect of rewinding the group file to allow repeated 
searches. Endgrent may be called to close the group file when processing is complete. 

Fgetgrent returns a p>ointer to the next group structure in the stream /, which 
matches the format of /etc/group. 


FILES 


/etc/group 


SEE ALSO 

getlogin(3C), getpwent(3C), group(4). 


DIAGNOSTICS 

A NULL pointer is returned on EOF or error. 


WARNING 

The above routines use <stdio.h>, which causes them to increase the size of pro¬ 
grams, not otherwise using standard I/O, more than might be expected. 


BUGS 


All information is contained in a static area, so it must be copied if it is to be saved. 
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NAME 

getlogin — get login name 

SYNOPSIS 

char *getlogin ( ); 

DESCRIPTION 

Getlogin returns a pointer to the login name as found in /etc/utmp. It may be 
used in conjunction with getpwnam to locate the correct password file entry when the 
same user ID is shared by several login names. 

If getlogin is called within a process that is not attached to a terminal, it returns a 
NULL pointer. The correct procedure for determining the login name is to call 
cuserid, or to call getlogin and if it fails to call getpwuid. 

FILES 

/etc/utmp 

SEE ALSO 

cuserid(3S), getgrent(3C), getpwent(3C), utmp(4). 

DIAGNOSTICS 

Returns the NULL pointer if name is not found. 

BUGS 

The return values point to static data whose content is overwritten by each call. 
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NAME 

getopt — get option letter from argument vector 


SYNOPSIS 

int getopt (argc, argv, optstring) 
int argc; 

char **argv, *opstring; 

extern char *optarg; 
extern int optind, opterr; 


DESCRIPTION 

Getopt returns the next option letter in argv that matches a letter in optstring. Opt¬ 
string is a string of recognized option letters; if a letter is followed by a colon, the 
option is expected to have an argument that may or may not be separated from it 
by white space. Optarg is set to point to the start of the option argument on return 
from getopt. 


Getopt places in optind the argv index of the next argument to be processed. 
Because optind is external, it is normally initialized to zero automatically before the 
first call to getopt. 

When all options have been processed (i.e., up to the first non-option argument), 

getopt returns EOF. The special option-may be used to delimit the end of the 

options; EOF will be returned, and-will be skipped. 


DIAGNOSTICS 

Getopt prints an error message on stderr and returns a question mark (?) when it 
encounters an option letter not included in optstring. This error message may be dis¬ 
abled by setting opterr to a non-zero value. 


EXAMPLE 

The following code fragment shows how one might process the arguments for a com¬ 
mand that can take the mutually exclusive options a and b, and the options f and o, 
both of which require arguments: 

main (argc, argv) 
int argc; 
char **argv; 

{ 
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int c; 

extern char *optarg; 

extern int optind; 

• 

♦ 

while ((c = getopt(argc, argv, "abf:o:")) != EOF) 
switch (c) { 
case 'a': 

if (bflg) 

errflg++; 

else 

aflg-H-; 

break; 
case V: 

if (aflg) 

errflg++; 

else 

bproc( ); 

break; 

case 'f: 

ifile = optarg; 
break; 
case 'o': 

ofile = optarg; 
break; 
case 'V: 

errflg++; 

} 

if (errflg) { 

fprintf(stderr, "usage: . . . "); 
exit (2); 

} 

for ( ; optind < argc; optind++) { 
if (access(argv[optind], 4)) { 


} 


SEE ALSO 

getopt(l) in the ICON/UXV User Reference Manual. 
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NAME 

getpass — read a password 


SYNOPSIS 

char *getpass (prompt) 
char ^prompt; 


DESCRIPTION 

Getpass reads up to a newline or EOF from the file /dev/tty, after prompting on 
the standard error output with the null-terminated string prompt and disabling echo¬ 
ing. A pointer is returned to a null-terminated string of at most 8 characters. If 
/dev/tty cannot be opened, a NULL pointer is returned. An interrupt will ter¬ 
minate input and send an interrupt signal to the calling program before returning. 


FILES 

/dev/tty 

SEE ALSO 

crypt(3C). 


WARNING 

The above routine uses <stdio.h>, which causes it to increase the size of programs 
not otherwise using standard I/O, more than might be expected. 


BUGS 


The return value points to static data whose content is overwritten by each call. 
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NAME 

getpw — get name from UID 


SYNOPSIS 

int getpw (uid, buf) 
int uid; 
char *buf; 


DESCRIPTION 

Getpw searches the password file for a user id number that equals uid, copies the line 
of the password file in which uid was found into the array pointed to by buf, and 
returns 0. Getpw returns non-zero if uid cannot be found. 

This routine is included only for compatibility with prior systems and should not be 
used; see getpwent( 3C) for routines to use instead. 


FILES 


/etc/passwd 


SEE ALSO 

getpwent(3C), passwd(4). 


DIAGNOSTICS 

Getpw returns non-zero on error. 


WARNING 

The above routine uses <stdio.h>, which causes it to increase, more than might be 
expected, the size of programs not otherwise using standard I/O. 
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NAME 

getpwent, getpwuid, getpwnam, setpwent, endpwent, fgetpwent — get password file 
entry 


SYNOPSIS 

^include <pwd.h> 

struct passwd *getpwent ( ) 

struct passwd tgetpwuid (uid) 

1 int uid; 

struct passwd *getpwnam (name) 
char *name; 

void setpwent ( ) 

void endpwent ( ) 

struct passwd *fgetpwent (f) 

FILE *f; 


DESCRIPTION 

Getpwent, getpwuid and getpwnam each returns a pointer to an object with the fol¬ 
lowing structure containing the broken-out fields of a line in the /etc/passwd file. 
Each line in the file contains a “passwd” structure, declared in the <pwd.h> header 
file: 


struct passwd { 


char 

*pw_name; 

char 

*pw_passwd; 

int 

pw_uid; 

int 

pw_gid; 

char 

*pw_age; 

char 

*pw_comment; 

char 

*pw_gecos; 

char 

*pw_dir; 

char 

*pw_shell; 


This structure is declared in Kpwd.h> so it is not necessary to redeclare it. 
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The pw_comment field is unused; the others have meanings described in passwd(A). 

Getpwent when first called returns a pointer to the first passwd structure in the file; 
thereafter, it returns a pointer to the next passwd structure in the file; so successive 
calls can be used to search the entire file. Getpwuid searches from the beginning of 
the file until a numerical user id matching aid is found and returns a pointer to the 
particular structure in which it was found. Getpwnam searches from the beginning 
of the file until a login name matching name is found, and returns a pointer to the 
particular structure in which it was found. If an end-of-file or an error is encoun¬ 
tered on reading, these functions return a NULL pointer. 


A call to setpwent has the effect of rewinding the password file to allow repeated 
searches. Endpwent may be called to close the password file when processing is com¬ 
plete. 


Fgetpwent returns a pointer to the next passwd structure in the stream /, which 
matches the format of /etc/passwd. 


FILES 


/etc/passwd 


SEE ALSO 

getlogin(3C), getgrent(3C), passwd(4). 


DIAGNOSTICS 

A NULL pointer is returned on EOF or error. 


WARNING 

The above routines use <stdio.h>, which causes them to increase the size of pro¬ 
grams, not otherwise using standard I/O, more than might be expected. 


BUGS 


All information is contained in a static area, so it must be copied if it is to be saved. 
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NAME 

getutent, getutid, getutline, pututline, setutent, endutent, utmpname — access utmp 
file entry 


SYNOPSIS 

^include <utmp.h> 

struct utmp *getutent ( ) 

struct utmp *getutid (id) 
struct utmp *id; 

struct utmp *getutline (line) 
struct utmp *line; 

void pututline (utmp) 
struct utmp *utmp; 

void setutent ( ) 

void endutent ( ) 

void utmpname (file) 
char *file; 


DESCRIPTION 


Getutent, getutid and getutline each return a pointer to a structure of the following 
type: 


struct utmp { 
char 
char 
char 
short 
short 
struct 
short 
short 
} ut_exit; 


ut_user[8]; 
ut_id[4l; 
utjine 12]; 
ut_pid; 
ut_type; 
exit_status { 
e_termination; 
e_exit; 


}; 


time_t ut_time; 


/* User login name */ 

/* /etc/inittab id (usually line #) */ 
/* device name (console, lnxx) */ 

/* process id */ 

/* type of entry */ 

/* Process termination status */ 

/* Process exit status */ 

/* The exit status of a process 
* marked as DEAD^PROCESS. */ 

/* time entry was made */ 
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Getulent reads in the next entry from a uimp-like file. If the file is not already open, 
it opens it. If it reaches the end of the file, it fails. 

Getutid searches forward from the current point in the utmp file until it finds an 
entry with a utjtype matching id—>ut_type if the type specified is RUN_LVL, 
BOOT.TIME, OLD.TIME or NEW.TIME. If the type specified in id is INIT_PROCESS, 
LOGlN_PROCESS, USER_PROCESS or DEAD_PROCESS, then getutid will return a pointer 
to the first entry whose type is one of these four and whose uf_»d field matches 
id—>ut_id. If the end of file is reached without a match, it fails. 

Getutline searches forward from the current point in the utmp file until it finds an 
entry of the type LOGINJPROCESS or USER_PROCESS which also has a utjline string 
matching the line—>utjline string. If the end of file is reached without a match, it 
fails. 

Pututline writes out the supplied utmp structure into the utmp file. It uses getutid to 
search forward for the proper place if it finds that it is not already at the proper 
place. It is expected that normally the user of pututline will have searched for the 
proper entry using one of the getut routines. If so, pututline will not search. If putut¬ 
line does not find a matching slot for the new entry, it will add a new entry to the 
end of the file. 

Setutent resets the input stream to the beginning of the file. This should be done 
before each search for a new entry if it is desired that the entire file be examined. 

Endutent closes the currently open file. 

Utmpname allows the user to change the name of the file examined, from 
/etc/utmp to any other file. It is most often expected that this other file will be 
/etc/wtmp. If the file does not exist, this will not be apparent until the first 
attempt to reference the file is made. Utmpname does not open the file. It just 
closes the old file if it is currently open and saves the new' file name. 


FILES 


/etc/utmp 

/etc/wtmp 


SEE ALSO 

ttyslot(3C), utmp(4). 


DIAGNOSTICS 

A NULL pointer is returned upon failure to read, whether for permissions or having 
reached the end of file, or upon failure to write. 
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COMMENTS 

The most current entry is saved in a static structure. Multiple accesses require that 
it be copied before further accesses are made. Each call to either getutid or getutline 
sees the routine examine the static structure before performing more I/O. If the con¬ 
tents of the static structure match what it is searching for, it looks no further. For 
this reason to use getutline to search for multiple occurrences, it would be necessary 
to zero out the static after each success, or getutline would just return the same 
pointer over and over again. There is one exception to the rule about removing the 
structure before further reads are done. The implicit read done by pututline (if it 
finds that it is not already at the correct place in the file) will not hurt the contents 
of the static structure returned by the getutent, getutid or getutline routines, if the 
user has just modified those contents and passed the pointer back to pututline. 

These routines use buffered standard I/O for input, but pututline uses an unbuffered 
non-standard write to avoid race conditions between processes trying to modify the 
utmp and wtmp files. 
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NAME 

hsearch, hcreate, hdestroy — manage hash search tables 


SYNOPSIS 

^include <search.h> 

ENTRY *hsearch (item, action) 
ENTRY item; 

ACTION action; 

int hcreate (nel) 
unsigned nel; 

void hdestroy ( ) 


DESCRIPTION 

Hsearch is a hash-table search routine generalized from Ivnuth (6.4) Algorithm D. It 
returns a pointer into a hash table indicating the location at which an entry can be 
found. Item is a structure of type ENTRY (defined in the <.search.h~> header file) 
containing two pointers: item.key points to the comparison key, and item.data points 
to any other data to be associated with that key. (Pointers to types other than 
character should be cast to pointer-to-character.) Action is a member of an 
enumeration type ACTION indicating the disposition of the entry if it cannot be found 
in the table. ENTER indicates that the item should be inserted in the table at an 
appropriate point. FIND indicates that no entry should be made. Unsuccessful reso¬ 
lution is indicated by the return of a NULL pointer. Hcreate allocates sufficient space 
for the table, and must be called before hsearch is used. Nel is an estimate of the 
maximum number of entries that the table will contain. This number may be 
adjusted upward by the algorithm in order to obtain certain mathematically favor¬ 
able circumstances. Hdestroy destroys the search table, and may be followed by 
another call to hcreate. 


NOTES 

Hsearch uses open addressing with a multiplicative hash function. However, its 
source code has many other options available which the user may select by compiling 
the hsearch source with the following symbols defined to the preprocessor: 

DIV Use the remainder modulo table size as the hash function instead 

of the multiplicative algorithm. 

USCR Use a User Supplied Comparison Routine for ascertaining table 
membership. The routine should be named hcompar and should 
behave in a mannner similar to strcmp (see $tring(3C)). 
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CHAINED 

Use a linked list to resolve collisions. If this option is selected, the 
following other options become available. 

START Place new entries at the beginning of the linked list 
(default is at the end). 

SORTUP Keep the linked list sorted by key in ascending 
order. 

SORTDOWN 

Keep the linked list sorted by key in descending 
order. 


Additionally, there are preprocessor flags for obtaining debugging printout (—DDE- 
BUG) and for including a test driver in the calling routine (—DDRIVER). The 
source code should be consulted for further details. 


EXAMPLE 

The following example will read in strings followed by two numbers and store them 
in a hash table, discarding duplicates. It will then read in strings and find the 
matching entry in the hash table and print it out. 


^include <stdio.h> 
^include <search.h> 


struct info { /* this is the info stored in the table */ 

int age, room;/* other than the key. */ 

} i 

#define NUM_EMPL 5000 /* # of elements in search table */ 


main( ) 

{ 

/* space to store strings */ 
char string_space[NUM_EMPL*20]; 

/* space to store employee info */ 
struct info info_space[NUM_EMPL]; 

/* next avail space in string_space */ 
char *str_ptr = string_jspace; 

/* next avail space in info_space */ 
struct info *info_ptr = info_space; 

ENTRY item, *found_item, *hsearch( ); 

/* name to look for in table */ 
char name_to_find[30]; 
int i = 0; 

/* create table */ 

(void) hcreate(NUM_EMPL); 

while (scanf("%s%d%d”, str_ptr, &info_ptr—>age, 

&info_ptr—>room) != EOF && i++ < NUM_EMPL) { 
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/* put info in structure, and structure in item */ 

item.key = str_ptr; 

item.data = (char *)info_ptr; 

str_ptr += strlen(str_ptr) + 1; 

info_ptr-H-; 

/* put item into table */ 

(void) hsearch(item, ENTER); 

/* access table */ 

item.key = name_toj6nd; 

while (scanf("%s", item.key) != EOF) { 

if ((found_item = hsearch(item, FIND)) != NULL) { 

/* if item is in the table */ 

(void)printf(”found %s, age = %d, room = %d\n”, 
found_item—>key, 

((struct info *)found_item—>data)—>age, 
((struct info *)found_item—>data)—>room); 

} else { 

(void)printf(*'no such employee %s\n", 
name_to_find) 


SEE ALSO 

bsearch(3C), lsearch(3C), malloc(3C), malloc(3X), string(3C), tsearch(3C). 


DIAGNOSTICS 

Hsearch returns a NULL pointer if either the action is FIND and the item could 
not be found or the action is ENTER and the table is full. Hcreate returns 
zero if it cannot allocate sufficient space for the table. 


WARNING 

Hsearch and hcreate use malloc( 3C) to allocate space. 


BUGS 


Only one hash search table may be active at any given time. 
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NAME 

13tol, ltol3 — convert between 3-byte integers and long integers 


SYNOPSIS 

void 13tol (lp, cp, n) 
long *lp; 
char *cp; 
int n; 

void ltol3 (cp, lp, n) 
char *cp; 
long *lp; 
int n; 


DESCRIPTION 

LStol converts a list of n three-byte integers packed into a character string pointed 
to by cp into a list of long integers pointed to by lp. 

LtolS performs the reverse conversion from long integers (lp) to three-byte integers 
(cp). 

These functions are useful for file-system maintenance where the block numbers are 
three bytes long. 


SEE ALSO 
fs(4). 


BUGS 


Because of possible differences in 
integers are machine-dependent. 


byte ordering, the numerical values of the long 
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NAME 

lockf — record locking on files 


SYNOPSIS 

# include <unistd.h> 

lockf (fildes, function, size) long size; int fildes, function; 


DESCRIPTION 

The lockf call will allow sections of a file to be locked (advisory write locks). (Man¬ 
datory or enforcement mode record locks are not currently available.) Locking calls 
from other processes which attempt to lock the locked file section will either return 
an error value or be put to sleep until the resource becomes unlocked. All the locks 
for a process are removed when the process terminates. [See fcntl( 2) for more infor¬ 
mation about record locking.] 

Fildes is an open file descriptor. The file descriptor must have O.WRONLY or 0_RDWR 
permission in order to establish a lock with this function call. 


Function is a control value which specifies the action to be taken. The permissible 
values for function are defined in <unistd.h> as follows: 


^define 

#define 

#define 

#define 


F_ULOCK 0 
FJLOCK 1 
F.TLOCK 2 
F_TEST 3 


/* Unlock a previously locked section */ 

/* Lock a section for exclusive use */ 

/* Test and lock a section for exclusive use */ 
/* Test section for other processes locks */ 


All other values of function are reserved for future extensions and will result in an 
error return if not implemented. 

F_TEST is used to detect if a lock by another process is present on the specified sec¬ 
tion. F_LOCK and F_TLOCK both lock a section of a file if the section is available. 
F.UNLOCK removes locks from a section of the file. 


Size is the number of contiguous bytes to be locked or unlocked. The resource to be 
locked starts at the current offset in the file and extends forward for a positive size 
and backward for a negative size. If size is zero, the section from the current offset 
through the largest file offset is locked (i.e., from the current offset through the 
present or any future end-of-file). An area need not be allocated to the file in order 
to be locked, as such locks may exist past the end-of-file. 

The sections locked with F_LOCK or F_TLOCK may, in whole or in part, contain or be 
contained by a previously locked section for the same process. When this occurs, or 
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if adjacent sections occur, the sections are combined into a single section. If the 
request requires that a new element be added to the table of active locks and this 
table is already full, an error is returned, and the new section is not locked. 

FJLOCK and F_TLOCK requests differ only by the action taken if the resource is not 
available. FJLOCK will cause the calling process to sleep until the resource is avail¬ 
able. F_TLOCK will cause the function to return a —1 and set errno to [EACCESS] 
error if the section is already locked by another process. 

F_ULOCK requests may, in whole or in part, release one or more locked sections con¬ 
trolled by the process. When sections are not fully released, the remaining sections 
are still locked by the process. Releasing the center section of a locked section 
requires an additional element in the table of active locks. If this table is full, an 
[EDEADLK] error is returned and the requested section is not released. 

A potential for deadlock occurs if a process controlling a locked resource is put to 
sleep by accessing another process’s locked resource. Thus calls to lock or fcntl scan 
for a deadlock prior to sleeping on a locked resource. An error return is made if 
sleeping on the locked resource would cause a deadlock. 

Sleeping on a resource is interrupted with any signal. The alarm( 2) command may 
be used to provide a timeout facility in applications which require this facility. 


ERRORS 

The lockf utility will fail if one or more of the following are true: 

[EBADF] 

Fildes is not a valid open descriptor. 

[EACCESS] 

Cmd is FJTLOCK or F_TEST and the section is already locked by another pro¬ 
cess. 

[EDEADLK] 

Cmd is FJLOCK or FJTLOCK and a deadlock would occur. Also the cmd is 
either of the above or F.ULOCK and the number of entries in the lock table 
would exceed the number allocated on the system. 


RETURN VALUE 

Upon successful completion, a value of 0 is returned. Otherwise, a value of —1 is 
returned and errno is set to indicate the error. 


CAVEATS 

Unexpected results may occur in processes that do buffering in the user address 
space. The process may later read/write data which is/was locked. The standard 
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I/O package is the most common source of unexpected buffering. 

SEE ALSO 

close(2), creat(2), fcntl(2), intro(2), open(2), read(2), write(2). 
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NAME 

lsearch, lfind — linear search and update 


SYNOPSIS 

#include <stdio.h> 

^include <search.h> 

char *lsearch ((char *)key, (char *)base, nelp, sizeof(*key), compar) 
unsigned *nelp; 
int (*compar)( ); 

char *lfind ((char *)key, (char *)base, nelp, sizeof(*key), compar) 
unsigned *nelp; 
int (*compar)( ); 


DESCRIPTION 

Lsearch is a linear search routine generalized from Knuth (6.1) Algorithm S. It 
returns a pointer into a table indicating where a datum may be found. If the datum 
does not occur, it is added at the end of the table. Key points to the datum to be 
sought in the table. Base points to the first element in the table. Nelp points to 
an integer containing the current number of elements in the table. The integer is 
incremented if the datum is added to the table. Compar is the name of the com¬ 
parison function which the user must supply ( strcmp , for example). It is called with 
two arguments that point to the elements being compared. The function must 
return zero if the elements are equal and non-zero otherwise. 

Lfind is the same as lsearch except that if the datum is not found, it is not added to 
the table. Instead, a NULL pointer is returned. 


NOTES 

The pointers to the key and the element at the base of the table should be of type 
pointer-to-element, and cast to type pointer-to-character. 

The comparison function need not compare every byte, so arbitrary data may be 
contained in the elements in addition to the values being compared. 

Although declared as type pointer-to-character, the value returned should be cast 
into type pointer-to-element. 


EXAMPLE 

This fragment will read in < TABSIZE strings of length < ELSIZE and store them in 
a table, eliminating duplicates. 
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^include <stdio.h> 

#include <search.h> 

#define TABSIZE 50 
#define ELSIZE 120 

char line [ELSIZE], tab [TABSIZE] [ELSIZE], *lsearch( ); 
unsigned nel = 0; 
int strcmp( ); 

while (fgets(line, ELSIZE, stdin) != NULL &,&, 
nel < TABSIZE) 

(void) lsearch(line, (char *)tab, &nel, 

ELSIZE, strcmp); 


SEE ALSO 

bsearch(3C), hsearcb(3C), tsearch(3C). 


DIAGNOSTICS 

If the searched for datum is found, both Isearch and Ifind return a pointer to 
it. Otherwise, Ifind returns NULL and Isearch returns a pointer to the newly 
added element. 


BUGS 


Undefined results can occur if there is not enough room in the table to add a 
new item. 
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NAME 

malloc, free, realloc, calloc — main memory allocator 


SYNOPSIS 

char *malloc (site) 
unsigned size; 

void free (ptr) 
char *ptr; 

char *realloc (ptr, size) 
char *ptr; 
unsigned size; 

char *calloc (nelem, elsize) 
unsigned nelem, elsize; 


DESCRIPTION 

Malloc and free provide a simple general-purpose memory allocation package. Mal¬ 
loc returns a pointer to a block of at least size bytes suitably aligned for any use. 


The argument to free is a pointer to a block previously allocated by malloc ; after 
free is performed this space is made available for further allocation, but its contents 
are left undisturbed. 


Undefined results will occur if the space assigned by malloc is overrun or if some ran¬ 
dom number is handed to free. 

Malloc allocates the first big enough contiguous reach of free space found in a circu¬ 
lar search from the last block allocated or freed, coalescing adjacent free blocks as it 
searches. It calls sbrk (see brk(2)) to get more memory from the system when there 
is no suitable space already free. 

Realloc changes the size of the block pointed to by ptr to size bytes and returns a 
pointer to the (possibly moved) block. The contents will be unchanged up to the 
lesser of the new and old sizes. If no free block of size bytes is available in the 
storage arena, then realloc will ask malloc to enlarge the arena by size bytes and 
will then move the data to the new space. 

Realloc also works if ptr points to a block freed since the last call of malloc , realloc, 
or calloc, thus sequences of free, malloc and realloc can exploit the search strategy of 
malloc to do storage compaction. 
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Calloc allocates space for an array of nelem elements of size elsize. The space is ini¬ 
tialized to zeros. 

Each of the allocation routines returns a pointer to space suitably aligned (after pos¬ 
sible pointer coercion) for storage of any type of object. 


SEE ALSO 

brk(2), malloc(3X). 


DIAGNOSTICS 

Malloc, realloc and calloc return a NULL pointer if there is no available memory or if 
the arena has been detectably corrupted by storing outside the bounds of a block. 
When this happens the block pointed to by ptr may be destroyed. 


NOTE 


Search time increases when many objects have been allocated; that is, if a program 
allocates but never frees, then each successive allocation takes longer. For an alter¬ 
nate, more flexible implementation, see malloc{ 3X). 
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NAME 

memccpy, memchr, memcmp, memcpy, memset — memory operations 


SYNOPSIS 

#include <memory.h> 

char *memccpy (si, s2, c, n) 
char *sl, *s2; 
int c, n; 

char *memchr (s, c, n) 
char *s; 
int c, n; 

int memcmp (si, s2, n) 
char *sl, *s2; 
int n; 

char *memcpy (si, s2, n) 
char *sl, *s2; 
int n; 

char *memset (s, c, n) 
char *s; 
int c, n; 


DESCRIPTION 

These functions operate as efficiently as possible on memory areas (arrays of charac¬ 
ters bounded by a count, not terminated by a null character). They do not check for 
the overflow of any receiving memory area. 

Memccpy copies characters from memory area s2 into si, stopping after the first 
occurrence of character c has been copied, or after n characters have been copied, 
whichever comes first. It returns a pointer to the character after the copy of c in 
si, or a NULL pointer if c was not found in the first n characters of s2. 


Memchr returns a pointer to the first occurrence of character c in the first n charac¬ 
ters of memory area s, or a NULL pointer if c does not occur. 


Memcmp compares its arguments, looking at the first n characters only, and returns 
an integer less than, equal to, or greater than 0, according as si is lexicographically 
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less than, equal to, or greater than s2. 

Memcpy copies n characters from memory area s2 to si. It returns si. 

Memset sets the first n characters in memory area s to the value of character c. It 
returns s. 


NOTE 

For user convenience, all these functions are declared in the optional <memory.h> 
header file. 


BUGS 


Memcmp uses native character comparison, which is signed on PDP-lls and VAX-lls, 
unsigned on other machines. Thus the sign of the value returned when one of the 
characters has its high-order bit set is implementation-dependent. 


Character movement is performed differently in different implementations. Thus 
overlapping moves may yield surprises. 
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( 


NAME 

mktemp — make a unique file name 


SYNOPSIS 

char *mktemp (template) 
char *template; 


DESCRIPTION 

Mktemp replaces the contents of the string pointed to by template by a unique file 
name, and returns the address of template. The string in template should look like a 
file name with six trailing Xs; mktemp will replace the Xs with a letter and the 
current process ID. The letter will be chosen so that the resulting name does not 
duplicate an existing file. 


SEE ALSO 

getpid(2), tmpfile(3S), tmpnam(3S). 


'1 

BUGS 


It is possible to run out of letters. 
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NAME 

monitor — prepare execution profile 


SYNOPSIS 

^include <mon.h> 


void monitor (lowpc, highpc, buffer, bufsize, nfunc) 
int (*lowpc)( ), (*highpc)( ); 

WORD ^buffer; 
int bufsize, nfunc; 


DESCRIPTION 

An executable program created by cc — p automatically includes calls for monitor 
with default parameters; monitor needn’t be called explicitly except to gain fine con¬ 
trol over profiling. 

Monitor is an interface to profil( 2). Lowpc and highpc are the addresses of two func¬ 
tions; buffer is the address of a (user supplied) array of bufsize WORDs (defined in the 
<mon.K> header file). Monitor arranges to record a histogram of periodically sam¬ 
pled values of the program counter, and of counts of calls of certain functions, in the 
buffer. The lowest address sampled is that of lowpc and the highest is just below 
highpc. Lowpc may not equal 0 for this use of monitor. At most nfunc call counts 
can be kept; only calls of functions compiled with the profiling option —p of cc(l) are 
recorded. (Except on the PDP-11, the C Library and Math Library supplied when cc 
—p is used also have call counts recorded.) 

For the results to be significant, especially where there are small, heavily used rou¬ 
tines, it is suggested that the buffer be no more than a few times smaller than the 
range of locations sampled. 

To profile the entire program, it is sufficient to use 
extern etext; 

monitor ((int (*)())2, etext, buf, bufsize, nfunc); 

Etext lies just above all the program text; see end( 3C). 


To stop execution monitoring and write the results on the file mon.out, use 
monitor ((int (*)())0, 0, 0, 0, 0); 
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Prof{ 1) can then be used to examine the results. 


FILES 


mon.out 

/lib/libp/libc.a 

/lib/libp/libm.a 


SEE ALSO 

profil(2), end(3C). 

cc(l), prof(l) in the ICON/UXV User Reference Manual. 
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NAME 

nlist — get entries from name list 


SYNOPSIS 

#include <nlist.h> 

int nlist (file-name, nl) 
char *file-name; 
struct nlist *nl; 


DESCRIPTION 

Nlist examines the name list in the executable file whose name is pointed to by file¬ 
name, and selectively extracts a list of values and puts them in the array of nlist 
structures pointed to by nl. The name list nl consists of an array of structures con¬ 
taining names of variables, types and values. The list is terminated with a null 
name; that is, a null string is in the name position of the structure. Each variable 
name is looked up in the name list of the file. If the name is found, the type and 
value of the name are inserted in the next two fields. The type field will be set to 0 
unless the file was compiled with the —g option. If the name is not found, both 
entries are set to 0. See a.out( 4) for a discussion of the symbol table structure. 

This function is useful for examining the system name list kept in the file /unix. In 
this way programs can obtain system addresses that are up to date. 


NOTES 

The <nlist.h> header file is automatically included by <a.out.h> for compatability. 
However, if the only information needed from <.a.out.li> is for use of nlist, then 
including <a.out.K> is discouraged. If <.a.out.li> is included, the line “#undef 
n_name” may need to follow it. 


SEE ALSO 

a.out(4). 


DIAGNOSTICS 

All value entries are set to 0 if the file cannot be read or if it does not contain a 
valid name list. 
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Nlist returns —1 upon error; otherwise it returns 0. 
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NAME 

perror, errno, sys_errlist, sys_nerr — system error messages 


SYNOPSIS 

void perror (s) 
char *s; 

extern int errno; 
extern char *sys_errlist[ ]; 
extern int sys_nerr; 


DESCRIPTION 

Perror produces a message on the standard error output, describing the last error 
encountered during a call to a system or library function. The argument string $ is 
printed first, then a colon and a blank, then the message and a new-line. To be of 
most use, the argument string should include the name of the program that incurred 
the error. The error number is taken from the external variable errno, which is set 
when errors occur but not cleared when non-erroneous calls are made. 

To simplify variant formatting of messages, the array of message strings sys_errlist 
is provided; errno can be used as an index in this table to get the message' string 
without the new-line. Sys_nerr is the largest message number provided for in the 
table; it should be checked because new error codes may be added to the system 
before they are added to the table. 


SEE ALSO 

intro(2). 
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NAME 

putenv — change or add value to environment 


SYNOPSIS 

int putenv (string) 
char ^string; 


DESCRIPTION 

. String points to a string of the form “name=value. ” Putenv makes the value of the 
environment variable name equal to value by altering an existing variable or creat¬ 
ing a new one. In either case, the string pointed to by string becomes part of the 
environment, so altering the string will change the environment. The space used by 
string is no longer used once a new string-defining name is passed to putenv. 


DIAGNOSTICS 

Putenv returns non-zero if it was unable to obtain enough space via malloc for an 
expanded environment, otherwise zero. 


SEE ALSO 

exec(2), getenv(3C), malloc(3C), environ(5). 


WARNINGS 

Putenv manipulates the environment pointed to by environ , and can be used in con¬ 
junction with getenv. However, envp (the third argument to main) is not changed. 
This routine uses malJoc(ZC) to enlarge the environment. 

After putenv is called, environmental variables are not in alphabetical order. 

A potential error is to call putenv with an automatic variable as the argument, then 
exit the calling function while string is still part of the environment. 
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NAME 

putpwent — write password file entry 


SYNOPSIS 

^include <pwd.h> 

int putpwent (p, f) 
struct passwd *p; 
FILE *f; 


DESCRIPTION 

Putpwent is the inverse of getpwent(3C). Given a pointer to a passwd structure 
created by getpwent (or getpwuid or getpwnam), putpwent writes a line on the stream 
/, which matches the format of /etc/passwd. 


DIAGNOSTICS 

Putpwent returns non-zero if an error was detected during its operation, otherwise 
zero. 


SEE ALSO 

getpwent(3C). 


WARNING 

The above routine uses <stdio.h>, which causes it to increase the size of programs, 
not otherwise using standard I/O, more than might be expected. 
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NAME 

qsort — quicker sort 


SYNOPSIS 

void qsort ((char *) base, nel, sizeof (*base), compar) 
unsigned nel; 
int (*compar)( ); 


DESCRIPTION 

Qsort is an implementation of the quicker-sort algorithm. It sorts a table of data in 
place. 

Base points to the element at the base of the table. Nel is the number of elements 
in the table. Compar is the name of the comparison function, which is called with 
two arguments that point to the elements being compared. As the function must 
return an integer less than, equal to, or greater than zero, so must the first argu¬ 
ment to be considered be less than, equal to, or greater than the second. 


NOTES 

The pointer to the base of the table should be of type pointer-to-element, and cast to 
type pointer-to-character. 

The comparison function need not compare every byte, so arbitrary data may be 
contained in the elements in addition to the values being compared. 

The order in the output of two items which compare as equal is unpredictable. 


SEE ALSO 

bsearch(3C), lsearch(3C), string(3C). 

sort(l) in the ICON/UXV User Reference Manual. 


Icon International, Inc. 


1 



RAND(3C) 
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NAME 

rand, srand — simple random-number generator 


SYNOPSIS 

int rand ( ) 

void srand (seed) 
unsigned seed; 


DESCRIPTION 

32 

Rand uses a multiplicative congruential random-number generator witl^ period 2 
that returns successive pseudo-random numbers in the range from 0 to 2 15 —1. 

Srand can be called at any time to reset the random-number generator to a random 
starting point. The generator is initially seeded with a value of 1. 


NOTE 


The spectral properties of rand leave a great deal to be desired. Drand^8{ 3C) pro¬ 
vides a much better, though more elaborate, random-number generator. 


SEE ALSO 

drand48(3C). 
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NAME 

setjmp, longjmp — non-local goto 


SYNOPSIS 

^include <setjmp.h> 

int setjmp (env) 
jmp_buf env; 

void longjmp (env, val) 
jmpjbuf env; 
int val; 


DESCRIPTION 

These functions are useful for dealing with errors and interrupts encountered in a 
low-level subroutine of a program. 

Setjmp saves its stack environment in env (whose type, jmpjbuf, is defined in the 
<setjmp.h> header file) for later use by longjmp. It returns the value 0. 

Longjmp restores the environment saved by the last call of setjmp with the 
corresponding env argument. After longjmp is completed, program execution contin¬ 
ues as if the corresponding call of setjmp (which must not itself have returned in the 
interim) had just returned the value val. Longjmp cannot cause setjmp to return the 
value 0. If longjmp is invoked with a second argument of 0, setjmp will return 1. All 
accessible data had values as of the time longjmp was called. 


SEE ALSO 

signal(2). 


WARNING 

If longjmp is called even though env was never primed by a call to setjmp, or when 
the last such call was in a function which has since returned, absolute chaos is 
guaranteed. 
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SLEEP (3C) COMPATIBILITY ROUTINES SLEEP (3C) 

NAME 

sleep — suspend execution for interval 


SYNOPSIS 

unsigned sleep (seconds) 
unsigned seconds; 


DESCRIPTION 

The current process is suspended from execution for the number of seconds specified 
by the argument. The actual suspension time may be less than that requested for 
two reasons: (1) Because scheduled wakeups occur at fixed 1-second intervals, (on the 
second, according to an internal clock) and (2) because any caught signal will ter¬ 
minate the sleep following execution of that signal’s catching routine. Also, the 
suspension time may be longer than requested by an arbitrary amount due to the 
scheduling of other activity in the system. The value returned by sleep will be the 
“unslept” amount (the requested time minus the time actually slept) in case the 
caller had an alarm set to go off earlier than the end of the requested sleep time, or 
premature arousal due to another caught signal. 

The routine is implemented by setting an alarm signal and pausing until it (or some 
other signal) occurs. The previous state of the alarm signal is saved and restored. 
The calling program may have set up an alarm signal before calling sleep. If the 
sleep time exceeds the time till such alarm signal, the process sleeps only until the 
alarm signal would have occurred. The caller’s alarm catch routine is executed just 
before the sleep routine returns. But if the sleep time is less than the time till such 
alarm, the prior alarm time is reset to go off at the same time it would have without 
the intervening sleep. 


SEE ALSO 

alarm(2), pause(2), signal(2). 
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NAME 

ssignal, gsignal — software signals 


SYNOPSIS 

^include <signal.h> 

int (*ssignal (sig, action))( ) 
int sig, (*action)( ); 

int gsignal (sig) 
int sig; 


DESCRIPTION 

Ssig?ial and gsignal implement a software facility similar to signal(2). This facility is 
used by the Standard C Library to enable users to indicate the disposition of error 
conditions, and is also made available to users for their own purposes. 


Software signals made available to users are associated with integers in the inclusive 
range 1 through 15. A call to ssignal associates a procedure, action, with the 
software signal sig ; the software signal, sig, is raised by a call to gsignal. Raising a 
software signal causes the action established for that signal to be taken. 


The first argument to ssignal is a number identifying the type of signal for which an 
action is to be established. The second argument defines the action; it is either the 
name of a (user-defined) action function or one of the manifest constants SIGJDFL 
(default) or SIG_JGN (ignore). Ssignal returns the action previously established for 
that signal type; if no action has been established or the signal number is illegal, 
ssignal returns SIGJDFL 

Gsignal raises the signal identified by its argument, sig: 


If an action function has been established for sig, then that action is reset to 
SIGJDFL and the action function is entered with argument sig. Gsignal returns 
the value returned to it by the action function. 

If the action for sig is SIGJGN, gsignal returns the value 1 and takes no other 
action. 

If the action for sig is SIGJDFL, gsignal returns the value 0 and takes no other 
action. 
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If sig has an illegal value or no action was ever specified for sig, gsignal returns 
the value 0 and takes no other action. 


SEE ALSO 

signal(2). 


NOTES 

There are some additional signals with numbers outside the range 1 through 15 
which are used by the Standard C Library to indicate error conditions. Thus, some 
signal numbers outside the range 1 through 15 are legal, although their use may 
interfere with the operation of the Standard C Library. 
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COMPATIBILITY ROUTINES 


STDIPC (3C) 


NAME 

ftok — standard interprocess communication package 


SYNOPSIS 

^include <sys/types.h> 
#in elude <sys/ipc.h> 

key_t ftok(path, id) 
char *path; 
char id; 


DESCRIPTION 

All interprocess communication facilities require the user to supply a key to be used 
by the msgget(2), semget( 2), and shmget(2) system calls to obtain interprocess com¬ 
munication identifiers. One suggested method for forming a key is to use the ftok 
subroutine described below. Another way to compose keys is to include the project 
ID in the most significant byte and to use the remaining portion as a sequence 
number. There are many other ways to form keys, but it is necessary for each sys¬ 
tem to define standards for forming them. If some standard is not adhered to, it will 
be possible for unrelated processes to unintentionally interfere with each other’s 
operation. Therefore, it is strongly suggested that the most significant byte of a key 
in some sense refer to a project so that keys do not conflict across a given system. 

Ftok returns a key based on path and id that is usable in subsequent msgget, semget, 
and shmget system calls. Path must be the path name of an existing file that is 
accessible to the process. Id is a character which uniquely identifies a project. Note 
that ftok will return the same key for linked files when called with the same id and 
that it will return different keys when called with the same file name but different 
ids. 


SEE ALSO 

intro(2), msgget(2), semget(2), shmget(2). 


DIAGNOSTICS 

Ftok returns (key_t) —1 if path does not exist or if it is not accessible to the process. 


WARNING 

If the file whose path is passed to ftok is removed when keys still refer to the file, 
future calls to ftok with the same path and id will return an error. If the same file is 
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recreated, then ftok is likely to return a different key than it did the original time it 
was called. 
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NAME 

strcat, strncat, strcmp, strncmp, strcpy, strncpy, strlen, strchr, strrchr, strpbrk, 
strspn, strcspn, strtok — string operations 


SYNOPSIS 

^include <string.h> 

char *strcat (si, s2) 
char *sl, *s2; 

char *strncat (si, s2, n) 
char *sl, *s2; 
int n; 

int strcmp (si, s2) 
char *sl, *s2; 

int strncmp (si, s2, n) 
char *sl, *s2; 
int nj 

char *strcpy (si, s2) 
char *sl, *s2; 


char *strncpy (si, s2, n) 
char *sl, *s2; 
int n; 

int strlen (s) 
char *s; 

char *strchr (s, c) 
char *s; 
int c; 

char *strrchr (s, c) 
char *s; 
int c; 


char *strpbrk (si, s2) 
char *sl, *s2; 

int strspn (si, s2) 
char *sl, *s2; 
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int strcspn (si, s2) 
char *sl, *s2; 

char *strtok (si, s2) 
char *sl, *s2; 


DESCRIPTION 

The arguments si, s2 and s point to strings (arrays of characters terminated by a 
null character). The functions strcat, strncat, strcpy, and strncpy all alter si. These 
functions do not check for overflow of the array pointed to by si. 

Strcat appends a copy of string s2 to the end of string si. Strncat appends at most 
n characters. Each returns a pointer to the null-terminated result. 

Strcmp compares its arguments and returns an integer less than, equal to, or greater 
than 0, according as si is lexicographically less than, equal to, or greater than s2. 
Strncmp makes the same comparison but looks at at most n characters. 
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Strcpy copies string s2 to si, stopping after the null character has been copied. 
Strncpy copies exactly n characters, truncating s2 or adding null characters to si if 
necessary. The result will not be null-terminated if the length of s2 is n or more. 
Each function returns si. 

Strlen returns the number of characters in s, not including the terminating null char¬ 
acter. 

Strchr {strrchr) returns a pointer to the first (last) occurrence of character c in 
string s, or a NULL pointer if c does not occur in the string. The null character ter¬ 
minating a string is considered to be part of the string. 

Strpbrk returns a pointer to the first occurrence in string si of any character from 
string s2, or a NULL pointer if no character from s2 exists in si. 

Strspn (strcspn ) returns the length of the initial segment of string si which consists 
entirely of characters from (not from) string s2. 

Strtok considers the string si to consist of a sequence of zero or more text tokens 
separated by spans of one or more characters from the separator string s2. The first 
call (with pointer si specified) returns a pointer to the first character of the first 
token, and will have written a null character into si immediately following the 
returned token. The function keeps track of its position in the string between 
separate calls, so that subsequent calls (which must be made with the first argument 
a NULL pointer) will work through the string si immediately following that token. 
In this way subsequent calls will work through the string si until no tokens remain. 
The separator string s2 may be different from call to call. When no token remains 
in si, a NULL pointer is returned. 


NOTE 


For user convenience, all these functions are declared in the optional <.string.li> 
header file. 


BUGS 


Strcmp and strncmp use native character comparison, which is signed on PDP-lls and 
VAX-lls, unsigned on other machines. Thus the sign of the value returned when one 
of the characters has its high-order bit set is implementation-dependent. 


Character movement is performed differently in different implementations. Thus 
overlapping moves may yield surprises. 


Icon International, Inc. 


3 



STRTOD (3C) COMPATIBILITY ROUTINES STRTOD (3C) 

NAME 

strtod, atof — convert string to double-precision number 


SYNOPSIS 

double strtod (str, ptr) 
char *str, **ptr; 

double atof (str) 
char *str; 


DESCRIPTION 

Strtod returns as a double-precision floating-point number the value represented by 
the character string pointed to by str. The string is scanned up to the first unrecog¬ 
nized character. 

Strtod recognizes an optional string of “white-space” characters (as defined by 
isspace in ctype( 3C)), then an optional sign, then a string of digits optionally con¬ 
taining a decimal point, then an optional e or E followed by an optional sign or 
space, followed by an integer. 

If the value of ptr is not (char **)NULL, a pointer to the character terminating the 
scan is returned in the location pointed to by ptr. If no number can be formed, *ptr 
is set to str, and zero is returned. 

AtoJ(str) is equivalent to strtodfstr, (char **)NULL). 


SEE ALSO 

ctype(3C), scanf(3S), strtol(3C). 


DIAGNOSTICS 

If the correct value would cause overflow, ±HUGE is returned (according to the sign 
of the value), and errno is set to erange. 

If the correct value would cause underflow, zero is returned and errno is set to 
ERANGE. 
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NAME 

strtol, atol, atoi — convert string to integer 


SYNOPSIS 

long strtol (str, ptr, base) 
char *str, **ptr; 
int base; 

long atol (str) 
char *str; 


int atoi (str) 
char *str; 


DESCRIPTION 

Strlol returns as a long integer the value represented by the character string pointed 
to by str. The string is scanned up to the first character inconsistent with the base. 
Leading “white-space” characters (as defined by isspace in ctype(3C)) are ignored. 

If the value of ptr is not (char **)NULL, a pointer to the character terminating the 
scan is returned in the location pointed to by ptr. If no integer can be formed, that 
location is set to str, and zero is returned. 


If base is positive (and not greater than 36), it is used as the base for conversion. 
After an optional leading sign, leading zeros are ignored, and “Ox” or “OX” is ignored 
if base is 16. 

If base is zero, the string itself determines the base thusly: After an optional leading 
sign a leading zero indicates octal conversion, and a leading “Ox” or “OX” hexade¬ 
cimal conversion. Otherwise, decimal conversion is used. 

Truncation from long to int can, of course, take place upon assignment or by an 
explicit cast. 

Atol(str) is equivalent to strtolfstr, (char **)NULL, 10). 

Atoi(str) is equivalent to (int) strtolfstr, (char **)NULL, 10). 

SEE ALSO 

ctype(3C), scanf(3S), strtod(3C). 


Icon International, Inc. 


1 



STRTOL (3C) COMPATIBILITY ROUTINES STRTOL (3C) 

BUGS 

Overflow conditions are ignored. 
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NAME 

swab — swap bytes 


SYNOPSIS 

void swab (from, to, nbytes) 
char *from, Ho; 
int nbytes; 


DESCRIPTION 

Swab copies nbytes bytes pointed to by from to the array pointed to by to, exchang¬ 
ing adjacent even and odd bytes. It is useful for carrying binary data between PDP- 
11s and other machines. Nbytes should be even and non-negative. If nbytes is odd 
and positive swab uses nbytes—1 instead. If nbytes is negative, swab does nothing. 
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NAME 

tsearch, tfind, tdelete, twalk — manage binary search trees 


SYNOPSIS 

^include <search.h> 

char *tsearch ((char *) key, (char **) rootp, compar) 
int (*compar)( ); 

char *tfind ((char *) key, (char **) rootp, compar) 
int (*compar)( ); 


char *tdelete ((char *) key, (char **) rootp, compar) 
int (*compar)( ); 

void twalk ((char *) root, action) 
void (*action)( ); 


DESCRIPTION 

Tsearch, tfind, tdelete, and twalk are routines for manipulating binary search trees. 
They are generalized from Knuth (6.2.2) Algorithms T and D. All comparisons are 
done with a user-supplied routine. This routine is called with two arguments, the 
pointers to the elements being compared. It returns an integer less than, equal to, or 
greater than 0, according to whether the first argument is to be considered less than, 
equal to or greater than the second argument. The comparison function need not 
compare every byte, so arbitrary data may be contained in the elements in addition 
to the values being compared. 

Tsearch is used to build and access the tree. Key is a pointer to a datum to be 
accessed or stored. If there is a datum in the tree equal to *key (the value pointed 
to by key), a pointer to this found datum is returned. Otherwise, *key is inserted, 
and a pointer to it returned. Only pointers are copied, so the calling routine must 
store the data. Rootp points to a variable that points to the root of the tree. A 
NULL value for the variable pointed to by rootp denotes an empty tree; in this case, 
the variable will be set to point to the datum which will be at the root of the new 
tree. 


Like tsearch, tfind will search for a datum in the tree, returning a pointer to it if 
found. However, if it is not found, tfind will return a NULL pointer. The arguments 
for tfind are the same as for tsearch. 
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Tdelete deletes a node from a binary search tree. The arguments are the same as 
for tsearch. The variable pointed to by rootp will be changed if the deleted node 
was the root of the tree. Tdelete returns a pointer to the parent of the deleted node, 
or a NULL pointer if the node is not found. 

Twalk traverses a binary search tree. Root is the root of the tree to be traversed. 
(Any node in a tree may be used as the root for a walk below that node.) Action is 
the name of a routine to be invoked at each node. This routine is, in turn, called 
with three arguments. The first argument is the address of the node being visited. 
The second argument is a value from an enumeration data type typedef enum { 
preorder, postorder, endorder, leaf } VISIT; (defined in the <search.h> header file), 
depending on whether this is the first, second or third time that the node has been 
visited (during a depth-first, left-to-right traversal of the tree), or whether the node 
is a leaf. The third argument is the level of the node in the tree, with the root being 
level zero. 

The pointers to the key and the root of the tree should be of type pointer-to-element, 
and cast to type pointer-to-character. Similarly, although declared as type pointer- 
to-character, the value returned should be cast into type pointer-to-element. 
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EXAMPLE 


The following code reads in strings and stores structures containing a pointer to each 
string and a count of its length. It then walks the tree, printing out the stored 
strings and their lengths in alphabetical order. 


^include <search.h> 

^include <stdio.h> 

struct node { /* pointers to these are stored in the tree */ 

char *string; 
int length; 

}; 

char string_space[lOOOO]; /* space to store strings */ 
struct node nodes[500]; /* nodes to store */ 

struct node *root = NULL; /* this points to the root */ 


main( ) 


* 

/* 


char *strptr — string_space; 
struct node *nodeptr = nodes; 
void print_node( ), twalk( ); 
int i = 0, node_compare( ); 

while (gets(strptr) != NULL && i++ < 500) { 

/* set node */ 

nodeptr—>string = strptr; 

nodeptr—>length = strlen(strptr); 

/* put node into the tree */ 

(void) tsearch((char *)nodeptr, <fcroot, 
node_compare); 

/* adjust pointers, so we don’t overwrite tree */ 

strptr += nodeptr—>length + 1; 

nodeptr++; 

} 

twalk(root, print.jiode); 


This routine compares two nodes, based on an 
alphabetical ordering of the string field. 


*/ 

int 

node_compare(nodel, node2) 
struct node *nodel, *node2; 

return strcmp(nodel—>string, node2—>string); 

} 

/* 


*/ 


This routine prints out a node, the first time 
twalk encounters it. 
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TSEARCH (3C) 


COMPATIBILITY ROUTINES 


TSEARCH (3C) 


void 

print_node(node, order, level) 
struct node **node; 

VISIT order; 
int level; 

{ 

if (order = preorder I! order = leaf) { 

(void)printf("string = %20s, length = %d\n", 
(*node)—>string, (*node)—>length); 


SEE ALSO 

bsearch(3C), hsearch(3C), lsearch(3C). 


DIAGNOSTICS 

A NULL pointer is returned by tsearch ir there is not enough space available to 
create a new node. 

A NULL pointer is returned by tsearch, tfind and (delete if rootp is NULL on 
entry. 

If the datum is found, both tsearch and tfind return a pointer to it. If not, 
tfind returns NULL, and tsearch returns a pointer to the inserted item. 


WARNINGS 

The root argument to twalk is one level of indirection less than the rootp 
arguments to tsearch and tdelete. 

There are two nomenclatures used to refer to the order in which tree nodes are 
visited. Tsearch uses preorder, postorder and endorder to respectively refer to 
visting a node before any of its children, after its left child and before its right, 
and after both its children. The alternate nomenclature uses preorder, inorder 
and postorder to refer to the same visits, which could result in some confusion 
over the meaning of postorder. 


BUGS 


If the calling function alters the pointer to the root, results are unpredictable. 
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TTYNAME (3C) COMPATIBILITY ROUTINES TTYNAME (3C) 

NAME 

ttyname, isatty — find name of a terminal 


SYNOPSIS 

char *ttyname (fildes) 
int fildes; 

int isatty (fildes) 
int fildes; 


DESCRIPTION 

Ttyname returns a pointer to a string containing the null-terminated path name of 
the terminal device associated with file descriptor fildes. 

Isatty returns 1 if fildes is associated with a terminal device, 0 otherwise. 


FILES 

/dev/* 


DIAGNOSTICS 

Ttyname returns a NULL pointer if fildes does not describe a terminal device in direc¬ 
tory /dev. 


BUGS 


The return value points to static data whose content is overwritten by each call. 
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TTYSL0T(3C) 


COMPATIBILITY ROUTINES 


TTYSLOT (3C) 


NAME 

ttyslot — find the slot in the utmp file of the current user 


SYNOPSIS 

int ttyslot ( ) 


DESCRIPTION 

Ttyslot returns the index of the current user’s entry in the /etc/utmp file. This is 
accomplished by actually scanning the file /etc/inittab for the name of the terminal 
associated with the standard input, the standard output, or the error output (0, 1 or 
2 ). 


FILES 


/etc/inittab 

/etc/utmp 


SEE ALSO 

getut(3C), ttyname(3C). 


DIAGNOSTICS 

A value of 0 is returned if an error was encountered while searching for the terminal 
name or if none of the above file descriptors is associated with a terminal device. 


Icon International, Inc. 





ABORT (3F) 


FORTRAN LIBRARY ROUTINES 


ABORT (3F) 


NAME 

abort — terminate Fortran program 


SYNOPSIS 

call abort ( ) 


DESCRIPTION 

Abort terminates the program which calls it, closing all open files truncated to the 
current position of the file pointer. The abort usually results in a core dump. 


DIAGNOSTICS 

When invoked, abort prints “Fortran abort routine called” on the standard error 
output. The message “abort - core dumped” is sent to the terminal. 


SEE ALSO 

abort(3C). 


Icon International, Inc. 


1 




ABS (3F) 


FORTRAN LIBRARY ROUTINES 


ABS (3F) 


NAME 

abs, iabs, dabs, cabs, zabs — Fortran absolute value 


SYNOPSIS 

integer il, i2 
real rl, r2 

double precision dpi, dp2 

complex cxl, cx2 

double complex dxl, dx2 

r2 = abs(rl) 

i2 = iabs(il) 

i2 = abs(il) 

dp2 = dabs(dpl) 

dp2 = abs(dpl) 

cx2 = cabs(cxl) 

cx2 = abs (cxl) 

dx2 = zabs(dxl) 

dx2 = abs(dxl) 


DESCRIPTION 

Abs is the family of absolute value functions. labs returns the integer absolute value 
of its integer argument. Dabs returns the double-precision absolute value of its 
double-precision argument. Cabs returns the complex absolute value of its complex 
argument. Zabs returns the double-complex absolute value of its double-complex 
argument. The generic form abs returns the type of its argument. 


SEE ALSO 

floor(3M). 
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ACOS (3F) 


FORTRAN LIBRARY ROUTINES 


ACOS (3F) 


NAME 

acos, dacos — Fortran arccosine intrinsic function 


SYNOPSIS 

real rl, r2 

double precision dpi, dp2 
r2 — acos(rl) 
dp2 = dacos(dpl) 
dp2 = acos(dpl) 


DESCRIPTION 

Acos returns the real arccosine of its real argument. Dacos returns the double¬ 
precision arccosine of its double-precision argument. The generic form acos may be 
used with impunity as its argument will determine the type of the returned value. 


SEE ALSO 

trig(3M). 
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AIMAG (3F) 


FORTRAN LIBRARY ROUTINES 


AIMAG (3F) 


NAME 

aimag, dimag — Fortran imaginary part of complex argument 


SYNOPSIS 
real r 

complex cxr 
double precision dp 
double complex cxd 
r = aimag(cxr) 
dp = dimag(cxd) 


DESCRIPTION 

Aimag returns the imaginary part of its single-precision complex argument. Dimag 
returns the double-precision imaginary part of its double-complex argument. 
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NAME 

aint, dint — Fortran integer part intrinsic function 


SYNOPSIS 

realrl,r2 

double precision dpi, dp2 
r2 = aint(rl) 
dp2 = dint(dpl) 
dp2 = aint(dpl) 


DESCRIPTION 

Aint returns the truncated value of its real argument in a real. Dint returns the 
truncated value of its double-precision argument as a double-precision value. Aint 
may be used as a generic function name, returning either a real or double-precision 
value depending on the type of its argument. 
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ASIN (3F) 


FORTRAN LIBRARY ROUTINES 


ASIN (3F) 


NAME 

asin, dasin — Fortran arcsine intrinsic function 


SYNOPSIS 

real rl, r2 

double precision dpi, dp2 
r2 = asin(rl) 
dp2 = dasin(dpl) 
dp2 = asin(dpl) 


DESCRIPTION 

Asin returns the real arcsine of its real argument. Dasin returns the double¬ 
precision arcsine of its double-precision argument. The generic form asin may be 
used with impunity as it derives its type from that of its argument. 


SEE ALSO 

trig(3M). 
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ATAN (3F) FORTRAN LIBRARY ROUTINES AT AN ( 3F ) 

NAME 

atan, datan — Fortran arctangent intrinsic function 


SYNOPSIS 

real rl, r2 

double precision dpi, dp2 
r2 = atan(rl) 
dp2 = datan(dpl) 
dp2 = atan(dpl) 


DESCRIPTION 

Atan returns the real arctangent of its real argument. Datan returns the double¬ 
precision arctangent of its double-precision argument. The generic form atan may be 
used with a double-precision argument returning a double-precision value. 


SEE ALSO 

trig(3M). 

I 


* 
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ATAN2(3F) 


FORTRAN LIBRARY ROUTINES 


ATAN2 (3F) 


NAME 

atan2, datan2 — Fortran arctangent intrinsic function 


SYNOPSIS 

real rl, r2, r3 

double precision dpi, dp2, dp3 
r3 = atan2(rl, r2) 
dp3 = datan2(dpl, dp2) 
dp3 = atan2(dpl, dp2) 


DESCRIPTION 

Atan2 returns the arctangent of argl/arg2 as a real value. Datan2 returns the 
double-precision arctangent of its double-precision arguments. The generic form 
atan2 may be used with impunity with double-precision arguments. 


SEE ALSO 

trig(3M). 
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BOOL (3F) 


FORTRAN LIBRARY ROUTINES 


BOOL (3F) 


NAME 

and, or, xor, not, lshift, rshift — Fortran Bitwise Boolean functions 


SYNOPSIS 

integer i, j, k 
real a, b, c 

k = and(i, j) 
c = or(a, b) 
j = xor(i, a) 
j = not(i) 
k = lshift(i, j) 
k = rshift(i, j) 


DESCRIPTION 

The generic intrinsic Boolean functions and, or and xor return the value of the 
binary operations on their arguments. Not is a unary operator returning the one’s 
complement of its argument. Lshift and rshift return the value of the first argument 
shifted left or right, respectively, the number of times specified by the second 
(integer) argument. The Boolean functions are generic; that is, they are defined for 
all data types as arguments and return values. Where required, the compiler will 
generate appropriate type conversions. 


NOTE 

Although defined for all data types, use of Boolean functions on any but integer data 
is bizarre and will probably result in unexpected consequences. 


BUGS 


The implementation of the shift functions may cause large shift values to deliver 
weird results. 


SEE ALSO 

mil(3F). 
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C0NJG(3F) 


FORTRAN LIBRARY ROUTINES 


CONJG (3F) 


NAME 

conjg, dconjg — Fortran complex conjugate intrinsic function 


SYNOPSIS 

complex cxl, cx2 
double complex dxl, dx2 
cx2 = conjg(cxl) 
dx2 = dconjg(dxl) 


DESCRIPTION 

Conjg returns the complex conjugate of its complex argument. Dconjg returns the 
double-complex conjugate of its double-complex argument. 
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COS (3F) 


FORTRAN LIBRARY ROUTINES 


COS (3F) 


NAME 

cos, dcos, ccos — Fortran cosine intrinsic function 


SYNOPSIS 

real rl, r2 

double precision dpi, dp2 

complex cxl, cx2 

r2 = cos(rl) 

dp2 = dcos(dpl) 

dp2 = cos(dpl) 

cx2 = ccos(cxl) 

cx2 = cos(cxl) 


DESCRIPTION 

Cos returns the real cosine of its real argument. Dcos returns the double-precision 
cosine of its double-precision argument. Ccos returns the complex cosine of its com¬ 
plex argument. The generic form cos may be used with impunity as its returned 
type is determined by that of its argument. 


SEE ALSO 

trig(3M). 
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C0SH(3F) 


FORTRAN LIBRARY ROUTINES 


COSH (3F) 


NAME 

cosh, dcosh — Fortran hyperbolic cosine intrinsic function 


SYNOPSIS 

real rl, r2 

double precision dpi, dp2 
r2 = cosh(rl) 
dp2 = dcosh (dpi) 
dp2 = cosb(dpl) 


DESCRIPTION 

Cosh returns the real hyperbolic cosine of its real argument. Dcosh returns the 
double-precision hyperbolic cosine of its double-precision argument. The generic 
form cosh may be used to return the hyperbolic cosine in the type of its argument. 


SEE ALSO 

sinh(3M). 
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DIM (3F) 


FORTRAN LIBRARY ROUTINES 


DIM (3F) 


NAME 

dim, ddim, idim — positive difference intrinsic functions 


SYNOPSIS 

integer al, &2, &3 
a3 — idim(al, a2) 

real al, a2, a3 
a3 = dim(al, a2) 

double precision al, a2, a3 
a3 = ddim(al, a2) 


DESCRIPTION 

These functions return: 

al—a2 if al > a2 
0 if al <= a2 
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DPROD (3F) 


FORTRAN LIBRARY ROUTINES 


DPROD (3F) 


NAME 

dprod — double precision product intrinsic function 


SYNOPSIS 

real al, a2 
double precision a3 
a3 = dprod(al, a2) 


DESCRIPTION 

Dprod returns the double precision product of its real arguments. 
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EXP (3F) 


FORTRAN LIBRARY ROUTINES 


EXP (3F) 


NAME 

exp, dexp, cexp — Fortran exponential intrinsic function 


SYNOPSIS 

real rl, r2 

double precision dpi, dp2 

complex cxl, cx2 

r2 = exp(rl) 

dp2 = dexp(dpl) 

dp2 = exp(dpl) 

cx2 = cexp(cxl) 

cx2 = exp(cxl) 


DESCRIPTION 

Exp returns the real exponential function e x of its real argument. Dexp returns the 
double-precision exponential function of its double-precision argument. Cexp returns 
the complex exponential function of its complex argument. The generic function exp 
becomes a call to dexp or cexp as required, depending on the type of its argument. 


SEE ALSO 

exp(3M). 


Icon International, Inc. 


1 



FTYPE (3F) 


FORTRAN LIBRARY ROUTINES 


FTYPE (3F) 


NAME 

int, ifix, idint, real, float, sngl, dble, cmplx, dcmplx, ichar, char — explicit Fortran 
type conversion 


SYNOPSIS 

integer i, j 
real r, s 

double precision dp, dq 
complex cx 
double complex dcx 
character*./ ch 
i = int(r) 
i = int(dp) 
i = int(cx) 
i = int(dcx) 
i = ifix(r) 
i = idint(dp) 
r = real(i) 
r = real(dp) 
r = real(cx) 
r = real(dcx) 
r = float(i) 
r = sngl(dp) 
dp = dble(i) 
dp = dble(r) 
dp = dble(cx) 
dp = dble(dcx) 
cx = cmplx(i) 
cx = cmplx(i, j) 
cx = cmplx (r) 
cx = cmplx(r, s) 
cx = cmplx(dp) 
cx = cmplx(dp, dq) 
cx = cmplx(dcx) 
dcx = dcmplx(i) 
dcx = dcmplx(i, j) 
dcx = dcmplx(r) 
dcx = dcmplx(r, s) 
dcx := dcmplx(dp) 
dcx = dcmplx(dp, dq) 
dcx = dcmplx(cx) 
i — ichar(ch) 
ch — char(i) 


DESCRIPTION 

These functions perform conversion from one data type to another. The function int 
converts to integer form its real, double precision, complex, or double complex 
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FTYPE (3F) FORTRAN LIBRARY ROUTINES FTYPE (3F) 


argument. If the argument is real or double precision, int returns the integer whose 
magnitude is the largest integer that does not exceed the magnitude of the argument 
and whose sign is the same as the sign of the argument (i.e. truncation). For complex 
types, the above rule is applied to the real part, ifix and idint convert only real 
and double precision arguments respectively. The function real converts to real form 
an integer, double precision, complex, or double complex argument. If the argument is 
double precision or double complex, as much precision is kept as is possible. If the 
argument is one of the complex types, the real part is returned. The functions float 
and sngl convert only integer and double precision arguments respectively. The 
function dble converts any integer, real, complex, or double complex argument to 
double precision form. If the argument is of a complex type, the real part is 
returned. The function cmplx converts its integer, real, double precision, or double 
complex argument(s) to complex form. The function dcmplx converts to double com¬ 
plex form its integer, real, double precision, or complex argument(s). Either one or 
two arguments may be supplied to cmplx and dcmplx . If there is only one argu¬ 
ment, it is taken as the real part of the complex type and an imaginary part of zero 
is supplied. If two arguments are supplied, the first is taken as the real part and the 
second as the imaginary part. The function ichar converts from a character to an 
integer depending on the character’s position in the collating sequence. The function 
char returns the character in the ith position in the processor collating sequence 
where i is the supplied argument. For a processor capable of representing n charac¬ 
ters, 

ichar(char(i)) = i for 0 < i < n, and 

char(ichar(ch)) = ch for any representable character ch. 
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GETARG (3F) 


FORTRAN LIBRARY ROUTINES 


GETARG (3F) 


NAME 

getarg — return Fortran command-line argument 


SYNOPSIS 

ch&raeter*N c 
integer i 
call getarg(i, c) 


DESCRIPTION 

Getarg returns the i-th command-line argument of the current process. Thus, if a 
program were invoked via foo argl arg2 arg3 getarg(2, c) would return the 

string “arg2” in the character variable c. 

SEE ALSO 

getopt(3C). 
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GETENV (3F) 


FORTRAN LIBRARY ROUTINES 


GETENV (3F) 


NAME 

getenv — return Fortran environment variable 


SYNOPSIS 

charaeter*N c call getenv(*VARIABLE_NAME", c) 


DESCRIPTION 

Getenv returns the character-string value of the environment variable represented 
by its first argument into the character variable of its second argument. If no such 
environment variable exists, all blanks will be returned. 


SEE ALSO 

getenv(3C), environ(5). 
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NAME 

iargc — return the number of command line arguments 


SYNOPSIS 

integer i 


i = iargc( ) 


DESCRIPTION 

The iargc function returns the number of command line arguments passed to the 
program. Thus, if a program were invoked via 

foo argl arg2 arg3 

iargcf ) would return 3. 


SEE ALSO 

getarg(3F). 
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INDEX (3F) 


FORTRAN LIBRARY ROUTINES 


INDEX (3F) 


NAME 

index — return location of Fortran substring 


SYNOPSIS 

character*Nl chi 
character*N2 ch.2 
integer i 

i = index(chl, ch2) 


DESCRIPTION 

Index returns the location of substring ch2 in string chi. The value returned is the 
position at which substring ch2 starts, or 0 if it is not present in string chi. If N2 is 
greater than Nl, a zero is returned. 
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LEN (3F) FORTRAN LIBRARY ROUTINES 

NAME 

len — return length of Fortran string 


SYNOPSIS 

character*N ch 
integer i 
i = len(ch) 


DESCRIPTION 

Len returns the length of string ch. 


LEN (3F) 
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LOG (3F) 


FORTRAN LIBRARY ROUTINES 


LOG (3F) 


NAME 

log, alog, dlog, clog — Fortran natural logarithm intrinsic function 


SYNOPSIS 

real rl, r2 

double precision dpi, dp2 

complex cxl, cx2 

r2 — alog(rl) 

r2 = log(rl) 

dp2 = dlog(dpl) 

dp2 = log(dpl) 

cx2 = clog(cxl) 

cx2 = log(cxl) 


DESCRIPTION 

Alog returns the real natural logarithm of its real argument. Dlog returns the 
double-precision natural logarithm of its double-precision argument. Clog returns 
the complex logarithm of its complex argument. The generic function log becomes a 
call to alog, dlog, or clog depending on the type of its argument. 


SEE ALSO 

exp(3M). 
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LOG10(3F) 


FORTRAN LIBRARY ROUTINES 


LOG10(3F) 


NAME 

loglO, aloglO, dloglO — Fortran common logarithm intrinsic function 


SYNOPSIS 

real rl, r2 

double precision dpi, dp2 
r2 = aloglO(rl) 
r2 = loglO(rl) 
dp2 = dloglO(dpl) 
dp2 = loglO(dpl) 


DESCRIPTION 

AloglO returns the real common logarithm of its real argument. DloglO returns the 
double-precision common logarithm of its double-precision argument. The generic 
function loglO becomes a call to aloglO or dloglO depending on the type of its argu¬ 
ment. 


SEE ALSO 

exp(3M). 
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MAX(3F) FORTRAN LIBRARY ROUTINES MAX(3F) 

NAME 

max, maxO, amaxO, maxi, amaxl, dmaxl — Fortran maximum-value functions 


SYNOPSIS 

integer i, j, k, 1 
real a, b, c, d 

double precision dpi, dp2, dp3 
1 = max(i, j, k) 
c — max(a, b) 
dp = max(a, b, c) 
k — maxO(i, j) 
a = amaxO(i, j, k) 
i = maxi (a, b) 
d — amaxl (a, b, c) 
dp3 = dmaxl(dpl, dp2) 


DESCRIPTION 

The maximum-value functions return the largest of their arguments (of which there 
may be any number). Max is the generic form which can be used for all data types 
and takes its return type from that of its arguments (which must all be of the same 
type). MaxO returns the integer form of the maximum value of its integer argu¬ 
ments; amaxO, the real form of its integer arguments; maxi, the integer form of its 
real arguments; amaxl, the real form of its real arguments; and dmaxl, the double¬ 
precision form of its double-precision arguments. 


SEE ALSO 

min(3F). 
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MCLOCK (3F) 


FORTRAN LIBRARY ROUTINES 


MCLOCK (3F) 


NAME 

mclock — return Fortran time accounting 

SYNOPSIS 

integer i i — mclock( ) 


DESCRIPTION 

Mclock returns time accounting information about the current process and its child 
processes. The value returned is the sum of the current process’s user time and the 
user and system times of all child processes. 


SEE ALSO 

times(2), clock(3C), system(3F). 
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MIL(3F) 


FORTRAN LIBRARY ROUTINES 


MIL (3F) 


NAME 

ior, iand, not, ieor, ishft, ishftc, ibits, btest, ibset, ibclr, mvbits — bit field manipula¬ 
tion intrinsic functions and subroutines from the Fortran Military Standard (MIL- 
STD-1753). 


SYNOPSIS 

integer i, k, 1, m, n, len 
logical b 

i = ior(m, n) 

i = iand(m, n) 

i — not(m) 

i = ieor(m, n) 

i = ishft(m, k) 

i = ishftc(m, k, len) 

i = ibits(m, k, len) 

b = btest(n, k) 

i = ibset(n, k) 

i — ibclr(n, k) 

call mvbits(m, k, len, n, 1) 


DESCRIPTION 

ior, iand, not, ieor — return the same results as and, or, not, xor as defined in 
boot(3F). 

ishft, ishftc — m specifies the integer to be shifted, k specifies the shift count, k > 0 
indicates a left shift, k = 0 indicates no shift, k < 0 indicates a right shift. In 
ishft, zeros are shifted in. In ishftc, the rightmost len bits are shifted circularly k 
bits. If k is greater than the machine word-size, ishftc will not shift. 

Bit fields are numbered from right to left and the rightmost bit position is zero. The 
length of the len field must be greater than zero. 

ibits — extract a subfield of len bits from m starting with bit position k and extend¬ 
ing left for len bits. The result field is right justified and the remaining bits are set 
to zero. 


btest — The kth bit of argument n is tested. The value of the function is .TRUE, if 
the bit is 1 and .FALSE, if the bit is 0. 

ibset — the result is the value of n with the kth bit set to 1. 


ibclr — the result is the value of n with the kth bit set to 0. 
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MIL(3F) 


FORTRAN LIBRARY ROUTINES 


MIL(3F) 


mvbits — len bits are moved beginning at position k of argument m to position 1 of 
argument n. 

SEE ALSO 

bool(3f). 
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MIN (3F) 


FORTRAN LIBRARY ROUTINES 


MIN (3F) 


NAME 

min, minO, aminO, mini, aminl, dminl — Fortran minimum-value functions 


SYNOPSIS 

integer i, j, k, 1 
real a, b, c, d 

double precision dpi, dp2, dp3 
1 = min(i, j, k) 
c = min(a, b) 
dp = min(a, b, c) 
k = minO(i, j) 
a = aminO(i, j, k) 
i = minl(a, b) 
d = aminl(a, b, c) 
dp3 = dminl(dpl, dp2) 


DESCRIPTION 

The minimum-value functions return the minimum of their arguments (of which 
there may be any number). Min is the generic form which can be used for all data 
types and takes its return type from that of its arguments (which must all be of the 
same type). MinO returns the integer form of the minimum value of its integer argu¬ 
ments; aminO, the real form of its integer arguments; mini, the integer form of its 
real arguments; aminl , the real form of its real arguments; and dminl, the double¬ 
precision form of its double-precision arguments. 


SEE ALSO 

max(3F). 
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MOD (3F) 


FORTRAN LIBRARY ROUTINES 


MOD (3F) 


NAME 

mod, amod, dmod — Fortran remaindering intrinsic functions 


SYNOPSIS 

integer i, j, k 
real rl, r2, r3 

double precision dpi, dp2, dp3 

k = mod(i, j) 

r3 = amod(rl, r2) 

r3 = mod(rl, r2) 

dp3 = dmod(dpl, dp2) 

dp3 = mod(dpl, dp2) 


DESCRIPTION 

Mod returns the integer remainder of its first argument divided by its second argu¬ 
ment. Amod and dmod return, respectively, the real and double-precision whole 
number remainder of the integer division of their two arguments. The generic ver¬ 
sion mod will return the data type of its arguments. 
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RAND(3F) FORTRAN LroRARY ROUTINES RAND(3F) 

NAME 

ir&nd, rand, srand — random number generator 


SYNOPSIS 

integer iseed, i, irand 
double precision x, rand 

call srand(iseed) i = irand( ) x = rand( ) 


DESCRIPTION 

Irand generates successive pseudo-random integers in the range from 0 to 2**15—1. 
Rand generates pseudo-random numbers distributed in [0, 1.0]. Srand uses its integer 
argument to re-initialize the seed for successive invocations of irand and rand. 


SEE ALSO 

rand(3C). 
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FORTRAN LIBRARY ROUTINES 


ROUND (3F) 


NAME 

anint, dnint, nint, idnint — Fortran nearest integer functions 


SYNOPSIS 

integer i 
real rl, r2 

double precision dpi, dp2 

r2 = anint(rl) 

i = nint(rl) 

dp2 = anint(dpl) 

dp2 — dnint(dpl) 

i = nint(dpl) 

i = idnint(dpl) 


DESCRIPTION 

Anint returns the nearest whole real number to its real argument (i.e., int(a+0.5) if a 
> 0, int(a—0.5) otherwise). Dnint does the same for its double-precision argument. 
Nint returns the nearest integer to its real argument. Idnint is the double-precision 
version. Anint is the generic form of unint and dnint , performing the same opera¬ 
tion and returning the data type of its argument. Nint is also the generic form of 
idnint. 
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SIGN (3F) 


NAME 

sign, isign, dsign — Fortran transfer-of-sign intrinsic function 


SYNOPSIS 

integer i, j, k 
real rl, r2, r3 

double precision dpi, dp2, dp3 

k = isign (i, j) 

k = sign(i, j) 

r3 — sign(rl, r2) 

dp3 = dsign(dpl, dp2) 

dp3 = sign (dpi, dp2) 


DESCRIPTION 

Isign returns the magnitude of its first argument with the sign of its second argu¬ 
ment. Sign and dsign are its real and double-precision counterparts, respectively. 
The generic version is sign and will devolve to the appropriate type depending on its 
arguments. 
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NAME 

signal — specify Fortran action on receipt of a system signal 


SYNOPSIS 

integer i, intfc 
external intfc 
call signal(i, intfc) 


DESCRIPTION 

The argument i specifies the signal to be caught. Signal allows a process to specify a 
function to be invoked upon receipt of a specific signal. The first argument specifies 
which fault or exception. The second argument specifies the function to be invoked. 
NOTE: The interrupt processing function, intfc, does not take an argument. 


SEE ALSO 

kill(2), signal(2). 
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SIN (3F) 


NAME 

sin, dsin, csin — Fortran sine intrinsic function 


SYNOPSIS 

real rl, r2 

double precision dpi, dp2 

complex cxl, cx2 

r2 = sin(rl) 

dp2 — dsin(dpl) 

dp2 — sin(dpl) 

cx2 — csin (cxl) 

cx2 = sin (cxl) 


DESCRIPTION 

Sin returns the real sine of its real argument. Dsin returns the double-precision sine 
of its double-precision argument. Csin returns the complex sine of its complex argu¬ 
ment. The generic sin function becomes dsin or csin as required by argument type. 


SEE ALSO 

trig(3M). 
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FORTRAN LIBRARY ROUTINES 


SINH (3F) 


NAME 

sinh, dsinh — Fortran hyperbolic sine intrinsic function 


SYNOPSIS 

real rl, r2 

double precision dpi, dp2 
r2 = sinh(rl) 
dp2 = dsinh(dpl) 
dp2 = sinh(dpl) 


DESCRIPTION 

Sinh returns the real hyperbolic sine of its real argument. Dsinh returns the double¬ 
precision hyperbolic sine of its double-precision argument. The generic form sinh 
may be used to return a double-precision value when given a double-precision argu¬ 
ment. 


SEE ALSO 

sinh(3M). 
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SQRT (3F) 


NAME 

sqrt, dsqrt, csqrt — Fortran square root intrinsic function 


SYNOPSIS 

real rl, r2 

double precision dpi, dp2 

complex cxl, cx2 

r2 = sqrt(rl) 

dp2 = dsqrt(dpl) 

dp2 = sqrt(dpl) 

cx2 = csqrt(cxl) 

cx2 = sqrt(cxl) 


DESCRIPTION 

Sqrt returns the real square root of its real argument. Dsqrt returns the double¬ 
precision square root of its double-precision argument. Csqrt returns the complex 
square root of its complex argument. Sqrt, the generic form, will become dsqrt or 
csqrt as required by its argument type. 


SEE ALSO 

exp(3M). 
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FORTRAN LIBRARY ROUTINES 


STRCMP (3F) 


NAME 

lge, lgt, lie, lit — string comparison intrinsic functions 


SYNOPSIS 

character*N al, &2 
logical 1 

I = lge(al, a2) 

1 = lgt(al, a2) 

1 = lle(al, a2) 

1 = llt(al, a2) 


DESCRIPTION 

These functions return .TRUE, if the inequality holds and .FALSE, otherwise. 
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SYSTEM (3F) 


NAME 

system — issue a shell command from Fortran 


SYNOPSIS 

character*N c call system(c) 


DESCRIPTION 

System causes its character argument to be given to s/i(l) as input, as if the string 
had been typed at a terminal. The current process waits until the shell has com¬ 
pleted. 


SEE ALSO 

exec(2), system(3S). 

sh(l) in the ICON/UXV User Reference Manual. 


/ 
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FORTRAN LIBRARY ROUTINES 


TANH (3F) 


NAME 

tanh, dtanh — Fortran hyperbolic tangent intrinsic function 


SYNOPSIS 

real rl, r2 

double precision dpi, dp2 
r2 = tanh(rl) 
dp2 = dtanh(dpl) 
dp2 = tanh(dpl) 


DESCRIPTION 

Tanh returns the real hyperbolic tangent of its real argument. Dtanh returns the 
double-precision hyperbolic tangent of its double-precision argument. The generic 
form tanh may be used to return a double-precision value given a double-precision 
argument. 


SEE ALSO 

sinh(3M). 
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NAME 

tan, dtan — Fortran tangent intrinsic function 


SYNOPSIS 

real rl,r2 

double precision dpi, dp2 
r2 = tan(rl) 
dp2 = dtan(dpl) 
dp2 = tan(dpl) 


DESCRIPTION 

Tan returns the real tangent of its real argument. Dtan returns the double-precision 
tangent of its double-precision argument. The generic tan function becomes dtan as 
required with a double-precision argument. 


SEE ALSO 

trig(3M). 
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NAME 

jO, jl, jn, yO, yl, yn — Bessel functions 


SYNOPSIS 

^include <math.h> 

double jO (x) 
double x; 

double jl (x) 
double x; 

double jn (n, x) 
int n; 
double x; 

double yO (x) 
double x; 

double yl (x) 
double x; 

double yn (n, x) 
int n; 
double x; 


DESCRIPTION 

JO and jl return Bessel functions of x of the first kind of orders 0 and 1 respectively. 
Jn returns the Bessel function of x of the first kind of order n. 

YO and yl return Bessel functions of x of the second kind of orders 0 and 1 respec¬ 
tively. Yn returns the Bessel function of x of the second kind of order n. The value 
of x must be positive. 


DIAGNOSTICS 

Non-positive arguments cause yO, yl and yn to return the value —HUGE and to set 
errno to EDOM. In addition, a message indicating DOMAIN error is printed on the 
standard error output. 

Arguments too large in magnitude cause jO, jl, yO and yl to return zero and to set 
errno to ERANGE. In addition, a message indicating TLOSS error is printed on the 
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MATHEMATICAL FUNCTIONS 


BESSEL (3M) 


standard error output. 

These error-handling procedures may be changed with the function matherr( 3M). 

SEE ALSO 

matherr(3M). 
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MATHEMATICAL FUNCTIONS 


ERF (3M) 


NAME 

erf, erfc — error function and complementary error function 


SYNOPSIS 

^include <math.h> 

double erf (x) 
double x; 

double erfc (x) 
double x; 


DESCRIPTION 


Erf returns the error function of x, defined as — Jc^At. 

V7T o 

Erfc, which returns 1.0 — erf(x), is provided because of the extreme loss of relative 
accuracy if erf(x) is called for large x and the result subtracted from 1.0 (e.g., for x = 
5, 12 places are lost). 


SEE ALSO 

exp(3M). 
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EXP (3M) 


MATHEMATICAL FUNCTIONS 


EXP (3M) 


NAME 

exp, log, loglO, pow, sqrt — exponential, logarithm, power, square root functions 

SYNOPSIS 

^include <math.h> 

double exp (x) 
double x; 

double log (x) 
double x; 

double loglO (x) 
double x; 

double pow (x, y) 
double x, y; 

double sqrt (x) 
double x; 

DESCRIPTION 

Exp returns e x . 

Log returns the natural logarithm of x. The value of x must be positive. 

LoglO returns the logarithm base ten of x. The value of x must be positive. 

Pow returns x?. If x is zero, y must be positive. If x is negative, y must be an 
integer. 

Sqrt returns the non-negative square root of x. The value of x may not be negative. 


DIAGNOSTICS 

Exp returns HUGE when the correct value would overflow, or 0 when the correct 
value would underflow, and sets errno to ERANGE. 

Log and loglO return -HUGE and set errno to EDOM when x is non-positive. A mes¬ 
sage indicating DOMAIN error (or SING error when x is 0) is printed on the standard 
error output. 
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Pow returns 0 and sets errno to EDOM when x is 0 and y is non-positive, or when x is 
negative and y is not an integer. In these cases a message indicating DOMAIN error 
is printed on the standard error output. When the correct value for pow would 
overflow or underflow, pow returns ±HUGE or 0 respectively, and sets errno to 
ERANGE. 


Sqrt returns 0 and sets errno to EDOM when x is negative. A message indicating 
DOMAIN error is printed on the standard error output. 

These error-handling procedures may be changed with the function matherr( 3M). 


SEE ALSO 

hypot(3M), matherr(3M), sinh(3M). 
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MATHEMATICAL FUNCTIONS 


FLOOR (3M) 


NAME 

floor, ceil, fmod, fabs — floor, ceiling, remainder, absolute value functions 


SYNOPSIS 

^include <math.h> 

double floor (x) 
double x; 

double ceil (x) 
double x; 

double fmod (x, y) 
double x, y; 

double fabs (x) 
double x; 


DESCRIPTION 

Floor returns the largest integer (as a double-precision number) not greater than x. 
Ceil returns the smallest integer not less than x. 

Fmod returns the floating-point remainder of the division of x by y : zero if y is zero 
or if x/y would overflow; otherwise the number / with the same sign as x, such that x 
— *y +/for some integer », and j/| < Jyj. 

Fabs returns the absolute value of r, |xj. 


SEE ALSO 

abs(3C). 
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MATHEMATICAL FUNCTIONS 


GAMMA(3M) 


NAME 

gamma — log gamma function 


SYNOPSIS 

^include <math.h> 

double gamma (x) 
double x; 

extern int sign gam; 


DESCRIPTION 


Gamma returns ln(]r(x)l), where T(x) is defined as Je~ f t*~ l dt. The sign of T(x) is 

o 

returned in the external integer signgam. The argument i may not be a non-positive 
integer. 

The following C program fragment might be used to calculate T: 

if ((y = gamma(x)) > LN_MAXDOUBLE) 
error(); 

y = signgam * exp(y); 


where LN_MAXDOUBLE is the least value that causes exp(3M) to return a range error, 
and is defined in the <values.h~> header file. 


DIAGNOSTICS 

For non-negative integer arguments HUGE is returned, and errno is set to EDOM A 
message indicating SING error is printed on the standard error output. 

If the correct value would overflow, gamma returns HUGE and sets errno to 
ERANGE 


These error-handling procedures may be changed with the function matherr(SM). 
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SEE ALSO 

exp(3M), matherr(3M), values(5). 
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MATHEMATICAL FUNCTIONS 


HYPOT(3M) 


NAME 

hypot — Euclidean distance function 

SYNOPSIS 

^include <math.h> 

double hypot (x, y) 
double x, y; 

DESCRIPTION 

Hypot returns 

sqrt(x * x + y * y), 

taking precautions against unwarranted overflows. 

DIAGNOSTICS 

When the correct value would overflow, hypot returns HUGE and sets errno to 
ERANGE. 

These error-handling procedures may be changed with the function malherr( 3M). 

i 

SEE ALSO 

matherr(3M). 


Icon International, Inc. 


1 



MATHERR (3M) 


MATHEMATICAL FUNCTIONS 


MATHERR (3M) 


NAME 

matherr — error-handling function 


SYNOPSIS 

^include <math.h> 

int matherr (x) 
struct exception *x; 


DESCRIPTION 

Matherr is invoked by functions in the Math Library when errors are detected. Users 
may define their own procedures for handling errors, by including a function named 
matherr in their programs. Matherr must be of the form described above. When an 
error occurs, a pointer to the exception structure x will be passed to the user- 
supplied matherr function. This structure, which is defined in the <math.K> header 
file, is as follows: 


struct exception { 
int type; 
char *name; 

double argl, arg2, retval; 

}; 


The element type is an integer describing the type of error that has occurred, from 
the following list of constants (defined in the header file): 


DOMAIN 

SING 

OVERFLOW 

UNDERFLOW 

TLOSS 

PLOSS 


argument domain error 
argument singularity 
overflow range error 
underflow range error 
total loss of significance 
partial loss of significance 


The element name points to a string containing the name of the function that 
incurred the error. The variables argl and arg2 are the arguments with which the 
function was invoked. Retval is set to the default value that will be returned by the 
function unless the user’s matherr sets it to a different value. 

If the user’s matherr function returns non-zero, no error message will be printed, and 
err no will not be set. 
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If matherr is not supplied by the user, the default error-handling procedures, 
described with the math functions involved, will be invoked upon error. These pro¬ 
cedures are also summarized in the table below. In every case, errno is set to EDOM 
or ERANGE and the program continues. 


EXAMPLE 

#include <math.h> 
int 

matherr(x) 

register struct exception *x; 

{ 

switch (x—>type) { 
case DOMAIN: 

/* change sqrt to return sqrt(—argl), not 0 */ 
if (!strcmp(x—>name, "sqrt")) { 

x—>retval = sqrt(—x—>argl); 

return (0); /* print message and set errno */ 

case SING: 

/* all other domain or sing errors, print message and abort */ 
fprintf(stderr, "domain error in %s\n", x—>name); 
abort( ); 
case PLOSS: 

/* print detailed error message */ 
fprintf(stderr, "loss of significance in %s(%g) = %g\n", 
x—>name, x—>argl, x—>retval); 
return (l); /* take no other action */ 

} 

return (0); /* all other errors, execute default procedure */ 
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DEFAULT ERROR HANDLING PROCEDURES 


Ttives of Errors 

tVDe 

DOMAIN 

SING 

OVERFLOW 

UNDERFLOW 

TLOSS 

PLOSS 

ermo 

EDOM 

EDOM 

ERANGE 

ERANGE 

ERANGE 

ERANGE 

BESSEL: 




— 

M. 0 

* 

vO. vl. vn fare < 0) 

M. -H 

— 

— 

— 

— 

— 

EXP: 

— 

_ 

H 

0 

— 

— 

LOG. LOGIO: 







(arg < 0) 

M. -H 






(are - 0) 

— 

M. -H 

— 

— 

— 

— 

POW: 

_ 

_ 

±H 

0 

M. 


nee ** non-int 

M.O 



— 

— 

— 

0 ** non-Dos 







SORT: 

M. 0 

_ 

_ 

— 

— 

— 

GAMMA: 

— 

M.H 

H 

— 


_ 

HYPOT: 

— 

— 

H 

— 

— 

— 

SINH 

— 

— 

±H 

— 

— 

— 

COSH: 

— 

— 

H 

— 

_ i 

— 

SIN, COS. TAN: - 

— 

— 


M. 0 

* 


ASIN. ACOS. ATAN2: M. 0 

— 

— 


— 

— 



ABBREVIATIONS 

* As much as possible of the value is returned. 

M Message is printed (EDOM error). 

H HUGE is returned. 

—H —HUGE is returned. 

±H HUGE or —HUGE js returned. 

0 0 is returned._ 
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| NAME 

sinh, cosh, tanh — hyperbolic functions 


SYNOPSIS 

^include <math.h> 

double sinh (x) 
double x; 

double cosh (x) 
double x; 

double tanh (x) 
double x; 


DESCRIPTION 

Sinh, cosh, and tanh return, respectively, the hyberbolic sine, cosine and tangent of 
their argument. 


DIAGNOSTICS 

Sinh and cosh return HUGE (and sinh may return —HUGE for negative x ) when the 
correct value would overflow and set errno to ERANGE. 


These error-handling procedures may be changed with the function matherr{ 3M). 


SEE ALSO 

matherr(3M). 
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NAME 

sin, cos, tan, asin, acos, atan, atan2 — trigonometric functions 


SYNOPSIS 

#include <math.h> 

double sin (x) 
double x; 

double cos (x) 
double x; 

double tan (x) 
double x; 

double asin (x) 
double x; 

double acos (x) 
double x; 

double atan (x) 
double x; 

double atan2 (y, x) 
double y, x; 


DESCRIPTION 

Sin, cos and tan return respectively the sine, cosine and tangent of their argument, 
x, measured in radians. 

Asin returns the arcsine of x, in the range —n/2 to n/2. 

Acos returns the arccosine of x, in the range 0 to n. 

Atan returns the arctangent of x, in the range — n/2 to ir/2. 

Atan2 returns the arctangent of y/x, in the range — ir to n, using the signs of both 
arguments to determine the quadrant of the return value. 
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DIAGNOSTICS 

Sin, cos, and tan lose accuracy when their argument is far from zero. For arguments 
sufficiently large, these functions return zero when there would otherwise be a com¬ 
plete loss of significance. In this case a message indicating TLOSS error is printed on 
the standard error output. For less extreme arguments causing partial loss of 
significance, a PLOSS error is generated but no message is printed. In both cases, 
errno is set to ERANGE. 


If the magnitude of the argument of asin or acos is greater than one, or if both argu¬ 
ments of atan2 are zero, zero is returned and errno is set to EDOM In addition, a 
message indicating DOMAIN error is printed on the standard error output. 

These error-handling procedures may be changed with the function matherr(3M). 


SEE ALSO 

matherr(3M). 


2 


Icon International, Inc. 







CTERMID (3S) 


STANDARD I/O LIBRARY 
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NAME 

ctermid — generate file name for terminal 


SYNOPSIS 

^include <stdio.h> 
char *ctermid (s) 
char *s; 


DESCRIPTION 

Ctermid generates the path name of the controlling terminal for the current process, 
and stores it in a string. 

If s is a NULL pointer, the string is stored in an internal static area, the contents of 
which are overwritten at the next call to ctermid, and the address of which is 
returned. Otherwise, s is assumed to point to a character array of at least 
L_ctermid elements; the path name is placed in this array and the value of s is 
returned. The constant L_ctermid is defined in the <stdio.h> header file. 


NOTES 

The difference between ctermid and ttyname( 3C) is that ttyname must be handed a 
file descriptor and returns the actual name of the terminal associated with that file 
descriptor, while ctermid returns a string (/dev/tty) that will refer to the terminal 
if used as a file name. Thus ttyname is useful only if the process already has at least 
one file open to a terminal. 


SEE ALSO 

ttyname(3C). 
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NAME 

cuserid — get character login name of the user 


SYNOPSIS 

^include <stdio.h> 

char *cuserid (s) 
char *s; 


DESCRIPTION 

Cuserid generates a character-string representation of the login name that the 
owner of the current process is logged in under. If s is a NULL pointer, this represen¬ 
tation is generated in an internal static area, the address of which is returned. Oth¬ 
erwise, s is assumed to point to an array of at least L_cuserid characters; the 
representation is left in this array. The constant L_cuserid is defined in the 
<stdio.h> header file. 


DIAGNOSTICS 

If the login name cannot be found, cuserid returns a NULL pointer; if s is not a NULL 
pointer, a null character (\0) will be placed at s[Oj. 


SEE ALSO 

getlogin(3C), getpwent(3C). 
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NAME 

fclose, fflush — close or flush a stream 


SYNOPSIS 

^include <stdio.h> 

int fclose (stream) 
FILE ^stream; 

int fflush (stream) 
FILE ^stream; 


DESCRIPTION 

Fclose causes any buffered data for the named stream to be written out, and the 
stream to be closed. 

Fclose is performed automatically for all open files upon calling exit( 2). 

Fflush causes any buffered data for the named stream to be written to that file. The 
stream remains open. 


DIAGNOSTICS 

These functions return 0 for success, and EOF if any error (such as trying to write to 
a file that has not been opened for writing) was detected. 


SEE ALSO 

close(2), exit(2), fopen(3S), setbuf(3S). 
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NAME 

ferror, feof, clearerr, fileno — stream status inquiries 


SYNOPSIS 

^include <stdio.h> 

int ferror (stream) 
FILE ^stream; 

int feof (stream) 

, FILE ^stream; 

void clearerr (stream) 
FILE *stream; 


int fileno (stream) 
FILE *stream; 


DESCRIPTION 

Ferror returns non-zero when an I/O error has previously occurred reading from or 
writing to the named stream , otherwise zero. 

Feof returns non-zero when EOF has previously been detected reading the named 
input stream, otherwise zero. 

Clearerr resets the error indicator and EOF indicator to zero on the named stream. 

Fileno returns the integer file descriptor associated with the named stream ; see 
open( 2). 


NOTE 

All these functions are implemented as macros; they cannot be declared or rede- 
dared. 


SEE ALSO 

open(2), fopen(3S). 
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NAME 

fopen, freopen, fdopen — open a stream 


SYNOPSIS 

^include <stdio.h> 

FILE *fopen (file-name, type) 
char *file-name, *type; 


FILE *freopen (file-name, type, stream) 
char ♦file-name, *type; 

FILE *stream; 

FILE *fdopen (Sides, type) 
int Sides; 
char *type; 


DESCRIPTION 

Fopen opens the file named by file-name and associates a stream with it. Fopen 
returns a pointer to the FILE structure associated with the stream. 

File-name points to a character string that contains the name of the file to be 
opened. 

Type is a character string having one of the following values: 

"r" open for reading 

"w" truncate or create for writing 

"a" append; open for writing at end of file, or create for writing 

"r+” open for update (reading and writing) 

"w+" truncate or create for update 

"a+" append; open or create for update at end-of-file 


Freopen substitutes the named file in place of the open stream. The original stream 
is closed, regardless of whether the open ultimately succeeds. Freopen returns a 
pointer to the FILE structure associated with stream. 

Freopen is typically used to attach the preopened streams associated with stdin, 
stdout and stderr to other files. 
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Fdopen associates a stream with a file descriptor. File descriptors are obtained from 
open, dup, creat, or ptpe(2), which open files but do not return pointers to a FILE 
structure stream. Streams are necessary input for many of the Section 3S library 
routines. The type of stream must agree with the mode of the open file. 

When a file is opened for update, both input and output may be done on the result¬ 
ing stream. However, output may not be directly followed by input without an inter¬ 
vening / seek or rewind, and input may not be directly followed by output without an 
intervening / seek , rewind, or an input operation which encounters end-of-file. 

When a file is opened for append (i.e., when type is "a" or "a-!-"), it is impossible to 
overwrite information already in the file. Fseek may be used to reposition the file 
pointer to any position in the file, but when output is written to the file, the current 
file pointer is disregarded. All output is written at the end of the file and causes the 
file pointer to be repositioned at the end of the output. If two separate processes 
open the same file for append, each process may write freely to the file without fear 
of destroying output being written by the other. The output from the two processes 
will be intermixed in the file in the order in which it is written. 


SEE ALSO 

creat(2), dup(2), open(2), pipe(2), fclose(3S), fseek(3S). 


DIAGNOSTICS 

Fopen and freopen return a NULL pointer on failure. 
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NAME 

fread, fwrite — binary input/output 


SYNOPSIS 

^include <stdio.h> 

int fread (ptr, size, nitems, stream) 

char *ptr; 

int size, nitems; 

FILE *stream; 

int fwrite (ptr, size, nitems, stream) 

char *ptr; 

int size, nitems; 

FILE *stream; 


DESCRIPTION 

Fread copies, into an array pointed to by ptr, nitems items of data from the named 
input stream, where an item of data is a sequence of bytes (not necessarily ter¬ 
minated by a null byte) of length size. Fread stops appending bytes if an end-of-file 
or error condition is encountered while reading stream, or if nitems items have been 
read. Fread leaves the file pointer in stream, if defined, pointing to the byte follow¬ 
ing the last byte read if there is one. Fread does not change the contents of stream. 

Fwrite appends at most nitems items of data from the array pointed to by ptr to the 
named output stream. Fwrite stops appending when it has appended nitems items of 
data or if an error condition is encountered on stream. Fwrite does not change the 
contents of the array pointed to by ptr. 

The argument size is typically sizeof(*ptr) where the pseudo-function sizeof specifies 
the length of an item pointed to by ptr. If ptr points to a data type other than char 
it should be cast into a pointer to char. 


SEE ALSO 

read(2), write(2), fopen(3S), getc(3S), gets(3S), printf(3S), putc(3S), puts(3S), 
scanf(3S). 

DIAGNOSTICS 

Fread and fwrite return the number of items read or written. If size or nitems is 
non-positive, no characters are read or w'ritten and 0 is returned by both fread and 
fwrite. 
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BUGS 


On the PDP-11, the number of bytes transferred is the product of size and nitems, 
modulo 65536. 
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NAME 

fseek, rewind, ftell — reposition a file pointer in a stream 


SYNOPSIS 

^include <stdio.h> 

int fseek (stream, offset, ptrname) 
FILE » stream; 
long offset; 
int ptrname; 

void rewind (stream) 

FILE * stream; 

long ftell (stream) 

FILE ^stream; 


DESCRIPTION 

Fseek sets the position of the next input or output operation on the stream. The 
new position is at the signed distance offset bytes from the beginning, from the 
current position, or from the end of the file, according as ptrname has the value 0, 1, 
or 2. 

Reivind(stream) is equivalent to fseek(stream, 0L, 0), except that no value is 
returned. 

Fseek and rewind undo any effects of ungetc{ 3S). 

After fseek or rewind, the next operation on a file opened for update may be either 
input or output. 

Ftell returns the offset of the current byte relative to the beginning of the file associ¬ 
ated with the named stream. 


SEE ALSO 

lseek(2), fopen(3S), popen(3S), ungetc(3S). 


DIAGNOSTICS 

Fseek returns non-zero for improper seeks, otherwise zero. An improper seek can be, 
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for example, an /seek done on a file that has not been opened via fopen ; in particu¬ 
lar, /seek may not be used on a terminal, or on a file opened via popen( 3S). 


WARNING 

Although on the ICON/UXV system an offset returned by /tell is measured in bytes, 
and it is permissible to seek to positions relative to that offset, portability to non- 
UNIX systems requires that an offset be used by /seek directly. Arithmetic may not 
meaningfully be performed on such an offset, which is not necessarily measured in 
bytes. 
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NAME 

getc, getchar, fgetc, getw — get character or word from a stream 


SYNOPSIS 

^include <stdio.h> 

int getc (stream) 
FILE ^stream; 

int getchar () 

int fgetc (stream) 
FILE *stream; 

int getw (stream) 
FILE *stream; 


DESCRIPTION 

Getc returns the next character (i.e., byte) from the named input stream, as an 
integer. It also moves the file pointer, if defined, ahead one character in stream. 
Getchar is defined as getc(stdin). Getc and getchar are macros. 

Fgetc behaves like getc, but is a function rather than a macro. Fgetc runs more 
slowly than getc, but it takes less space per invocation and its name can be passed 
as an argument to a function. 

Getw returns the next word (i.e., integer) from the named input stream. Getw incre¬ 
ments the associated file pointer, if defined, to point to the next word. The size of a 
word is the size of an integer and varies from machine to machine. Getw assumes no 
special alignment in the file. 


SEE ALSO 

fclose(3S), ferror(3S), fopen(3S), fread(3S), gets(3S), putc(3S), scanf(3S). 


DIAGNOSTICS 

These functions return the constant EOF at end-of-file or upon an error. Because 
EOF is a valid integer, ferror( 3S) should be used to detect getw errors. 
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WARNING 

If the integer value returned by getc, getchar, or fgetc is stored into a character vari¬ 
able and then compared against the integer constant EOF, the comparison may 
never succeed, because sign-extension of a character on widening to integer is 
machine-dependent. 


BUGS 


Because it is implemented as a macro, getc treats incorrectly a stream argument 
with side effects. In particular, getc(*f++) does not work sensibly. Fgetc should be 
used instead. 

Because of possible differences in word length and byte ordering, files written using 
putw are machine-dependent, and may not be read using getw on a different proces¬ 
sor. 
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NAME 

gets, fgets — get a string from a stream 


SYNOPSIS 

^include <stdio.h> 

char *gets (s) 
char *s; 

char *fgets (s, n, stream) 
char *a; 
int n; 

FILE *stream; 


DESCRIPTION 

Gets reads characters from the standard input stream, stdin, into the array pointed 
to by s, until a new-line character is read or an end-of-file condition is encountered. 
The new-line character is discarded and the string is terminated with a null charac¬ 
ter. 

Fgets reads characters from the stream into the array pointed to by s, until n—1 
characters are read, or a new-line character is read and transferred to s, or an end- 
of-file condition is encountered. The string is then terminated with a null character. 


SEE ALSO 

ferror(3S), fopen(3S), fread(3S), getc(3S), scanf(3S). 


DIAGNOSTICS 

If end-of-file is encountered and no characters have been read, no characters are 
transferred to s and a NULL pointer is returned. If a read error occurs, such as try¬ 
ing to use these functions on a file that has not been opened for reading, a NULL 
pointer is returned. Otherwise s is returned. 
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NAME 

popen, pclose — initiate pipe to/from a process 


\ . 


SYNOPSIS 

^include <stdio.h> 

FILE *popen (command, type) 
char ^command, *type; 

int pclose (stream) 

FILE ^stream; 


DESCRIPTION 

The arguments to popen are pointers to null-terminated strings containing, respec¬ 
tively, a shell command line and an I/O mode, either r for reading or w for writing. 
Popen creates a pipe between the calling program and the command to be executed. 
The value returned is a stream pointer such that one can write to the standard 
input of the command, if the I/O mode is w, by writing to the file stream ; and one 
can read from the standard output of the command, if the I/O mode is r, by reading 
from the file stream. 

A stream opened by popen should be closed by pclose, which waits for the associated 
process to terminate and returns the exit status of the command. 

Because open files are shared, a type r command may be used as an input filter and 
a type w as an output filter. 


SEE ALSO 

pipe(2), wait(2), fclose(3S), fopen(3S), system(3S). 


DIAGNOSTICS 

Popen returns a NULL pointer if files or processes cannot be created, or if the shell 
cannot be accessed. 


Pclose returns —1 if stream is not associated with a “popened” command. 
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BUGS 


If the original and “popened” processes concurrently read or write a common file, 
neither should use buffered I/O, because the buffering gets all mixed up. Problems 
with an output filter may be forestalled by careful buffer flushing, e.g. with fflush-, see 
fclose( 3S). 
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NAME 

printf, fprintf, sprintf — print formatted output 


SYNOPSIS 

#include <stdio.h> 

int printf (format [, arg ] ... ) 
char *format; 

int fprintf (stream, format [, arg ] ... ) 
FILE ^stream; 
char *format; 

int sprintf (s, format [ , arg ] ... ) 
char *8, format; 


DESCRIPTION 

Printf places output on the standard output stream stdout. Fprintf places output on 
the named output stream. Sprintf places “output,” followed by the null character 
(\0), in consecutive bytes starting at *s; it is the user’s responsibility to ensure that 
enough storage is available. Each function returns the number of characters 
transmitted (not including the \0 in the case of sprintf), or a negative value if an 
output error was encountered. 


Each of these functions converts, formats, and prints its args under control of the 
format. The format is a character string that contains two types of objects: plain 
characters, which are simply copied to the output stream, and conversion 
specifications, each of which results in fetching of zero or more args. The results are 
undefined if there are insufficient args for the format. If the format is exhausted 
while args remain, the excess args are simply ignored. 

Each conversion specification is introduced by the character %. After the %, the 
following appear in sequence: 

Zero or more flags, which modify the meaning of the conversion specification. 

An optional decimal digit string specifying a minimum field width. If the con¬ 
verted value has fewer characters than the field width, it will be padded on 
the left (or right, if the left-adjustment flag described below, has been 
given) to the field width. If the field width for an s conversion is preceded by 
a 0, the string is right adjusted with zero-padding on the left. 


A precision that gives the minimum number of digits to appear for the d, o, 
u, x, or X conversions, the number of digits to appear after the decimal point 
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for the e and f conversions, the maximum number of significant digits for the 
g conversion, or the maximum number of characters to be printed from a 
string in s conversion. The precision takes the form of a period (.) followed 
by a decimal digit string; a null digit string is treated as zero. 

An optional 1 (ell) specifying that a following d, o, u, x, or X conversion char¬ 
acter applies to a long integer arg. A 1 before any other conversion character 
is ignored. 

A character that indicates the type of conversion to be applied. 


A field width or precision may be indicated by an asterisk (*) instead of a digit 
string. In this case, an integer arg supplies the field width or precision. The arg 
that is actually converted is not fetched until the conversion letter is seen, so the 
args specifying field width or precision must appear before the arg (if any) to be con¬ 
verted. 

The flag characters and their meanings are: 

— The result of the conversion will be left-justified within the field. 

+ The result of a signed conversion will always begin with a sign (+ or —). 

blank If the first character of a signed conversion is not a sign, a blank will be 

prefixed to the result. This implies that if the blank and + flags both 
appear, the blank flag will be ignored. 

This flag specifies that the value is to be converted to an “alternate 
form.” For c, d, s, and u conversions, the flag has no effect. For o 
conversion, it increases the precision to force the first digit of the result 
to be a zero. For x or X conversion, a non-zero result will have Ox or 
OX prefixed to it. For e, E, f, g, and G conversions, the result will 
always contain a decimal point, even if no digits follow the point (nor¬ 
mally, a decimal point appears in the result of these conversions only if a 
digit follows it). For g and G conversions, trailing zeroes will not be 
removed from the result (which they normally are). 

The conversion characters and their meanings are: 

d,o,u,x,x The integer arg is converted to signed decimal, unsigned octal, decimal, 
or hexadecimal notation (x and X), respectively; the letters abcdef are 
used for x conversion and the letters ABCDEF for X conversion. The pre¬ 
cision specifies the minimum number of digits to appear; if the value 
being converted can be represented in fewer digits, it will be expanded 
with leading zeroes. (For compatibility with older versions, padding with 
leading zeroes may alternatively be specified by prepending a zero to the 
field width. This does not imply an octal value for the field width.) The 
default precision is 1. The result of converting a zero value with a preci¬ 
sion of zero is a null string. 

The float or double arg is converted to decimal notation in the style 
“[—jddd.ddd,” where the number of digits after the decimal point is equal 
to the precision specification. If the precision is missing, six digits are 
output; if the precision is explicitly 0, no decimal point appears. 
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e,E 


g,G 


c 

s 


% 


The float or double arg is converted in the style “[—]d.ddde±dd,” where 
there is one digit before the decimal point and the number of digits after 
it is equal to the precision; when the precision is missing, six digits are 
produced; if the precision is zero, no decimal point appears. The E for¬ 
mat code will produce a number with E instead of e introducing the 
exponent. The exponent always contains at least two digits. 

The float or double arg is printed in style f or e (or in style E in the case 
of a G format code), with the precision specifying the number of 
significant digits. The style used depends on the value converted: style e 
will be used only if the exponent resulting from the conversion is less than 
—4 or greater than the precision. Trailing zeroes are removed from the 
result; a decimal point appears only if it is followed by a digit. 

The character arg is printed. 

The arg is taken to be a string (character pointer) and characters from 
the string are printed until a null character (\ 0 ) is encountered or the 
number of characters indicated by the precision specification is reached. 
If the precision is missing, it is taken to be infinite, so all characters up to 
the first null character are printed. A NULL value for arg will yield 
undefined results. 

Print a %; no argument is converted. 


In no case does a non-existent or small field width cause truncation of a field; if the 
result of a conversion is wider than the field width, the field is simply expanded to 
contain the conversion result. Characters generated by printJ and fprintf are printed 
as if putc{ 3S) had been called. 


EXAMPLES 

To print a date and time in the form “Sunday, July 3, 10:02,” where weekday and 
month are pointers to null-terminated strings: 


printf("%s, %s %d, %d:%.2d”, weekday, month, day, hour, min); 


To print ir to 5 decimal places: 


printf(”pi = %.5f", 4 * atan(l.O)); 


SEE ALSO 

ecvt(3C), putc(3S), scanf(3S), stdio(3S). 
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NAME 

putc, putchar, fputc, putw — put character or word on a stream 


SYNOPSIS 

^include <stdio.h> 

int putc (c, stream) 
int c; 

FILE *stream; 

int putchar (c) 
int c; 

int fputc (c, stream) 
int c; 

FILE *stream; 

int putw (w, stream) 
int w; 

FILE *stream; 


DESCRIPTION 

Putc writes the character c onto the output stream (at the position where the file 
pointer, if defined, is pointing). Putchar(c) is defined as putc(c, stdout). Putc and 
putchar are macros. 


Fputc behaves like putc, but is a function rather than a macro. Fputc runs more 
slowly than putc, but it takes less space per invocation and its name can be passed 
as an argument to a function. 


Putw writes the word (i.e. integer) w to the output stream (at the position at which 
the file pointer, if defined, is pointing). The size of a word is the size of an integer 
and varies from machine to machine. Putw neither assumes nor causes special align¬ 
ment in the file. 

Output streams, with the exception of the standard error stream stderr, are by 
default buffered if the output refers to a file and line-buffered if the output refers to 
a terminal. The standard error output stream stderr is by default unbuffered, but 
use of freopen (see fopen{ 3S)) will cause it to become buffered or line-buffered. When 
an output stream is unbuffered, information is queued for writing on the destination 
file or terminal as soon as written; when it is buffered, many characters are saved up 
and written as a block. When it is line-buffered, each line of output is queued for 
w’riting on the destination terminal as soon as the line is completed (that is, as soon 
as a new-line character is written or terminal input is requested). Setbuf(3S) or 
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Setbuf{ 3S) may be used to change the stream’s buffering strategy. 


SEE ALSO 

fclose(3S), ferror(3S), fopen(3S), fread(3S), printf(3S), puts(3S), setbuf(3S). 


DIAGNOSTICS 

On success, these functions each return the value they have written. On failure, 
they return the constant EOF. This will occur if the file stream is not open for writ¬ 
ing or if the output file cannot be grown. Because EOF is a valid integer, ferror{ 3S) 
should be used to detect putw errors. 


BUGS 


Because it is implemented as a macro, putc treats incorrectly a stream argument 
with side effects. In particular, putc(c, *f-Hf-); doesn’t work sensibly. Fputc should 
be used instead. 

Because of possible differences in word length and byte ordering, files written using 
putw are machine-dependent, and may not be read using getw on a different proces¬ 
sor. 
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NAME 

puts, fputs — put a string on a stream 


SYNOPSIS 

^include <stdio.h> 

int puts (s) 
char *s; 


int fputs (s, stream) 
char *s; 

FILE ^stream; 


DESCRIPTION 

Puts writes the null-terminated string pointed to by s, followed by a new-line char¬ 
acter, to the standard output stream stdout. 

Fputs writes the null-terminated string pointed to by s to the named output stream. 
Neither function writes the terminating null character. 


DIAGNOSTICS 

Both routines return EOF on error. This will happen if the routines try to write on a 
file that has not been opened for writing. 


SEE ALSO 

ferror(3S), fopen(3S), fread(3S), printf(3S), putc(3S). 


NOTES 

Puts appends a new-line character while fputs does not. 
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NAME 

scanf, fscanf, sscanf — convert formatted input 


SYNOPSIS 

#include <stdio.h> 

int scanf (format [ , pointer ] ... ) 
char *format; 

int fscanf (stream, format [, pointer ] ... ) 
FILE *stream; 
char *format; 


int sscanf (s, format [ , pointer ] ... ) 
char *s, ^format; 


DESCRIPTION 

Scanf reads from the standard input stream stdin. Fscanf reads from the named 
input stream. Sscanf reads from the character string s. Each function reads charac¬ 
ters, interprets them according to a format, and stores the results in its arguments. 
Each expects, as arguments, a control string format described below, and a set of 
pointer arguments indicating where the converted input should be stored. 

The control string usually contains conversion specifications, which are used to direct 
interpretation of input sequences. The control string may contain: 

1. White-space characters (blanks, tabs, new-lines, or form-feeds) which, except in 
two cases described below, cause input to be read up to the next non-white-space 
character. 

2. An ordinary character (not %), which must match the next character of the 
input stream. 

3. Conversion specifications, consisting of the character %, an optional assignment 
suppressing character *, an optional numerical maximum field width, an optional 
I (ell) or h indicating the size of the receiving variable, and a conversion code. 

A conversion specification directs the conversion of the next input field; the result is 
placed in the variable pointed to by the corresponding argument, unless assignment 
suppression was indicated by *. The suppression of assignment provides a way of 
describing an input field which is to be skipped. An input field is defined as a string 
of non-space characters; it extends to the next inappropriate character or until the 
field width, if specified, is exhausted. For all descriptors except “[” and “c”, white 
space leading an input field is ignored. 
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The conversion code indicates the interpretation of the input field; the corresponding 

pointer argument must usually be of a restricted type. For a suppressed field, no 

pointer argument is given. The following conversion codes are legal: 

% a single % is expected in the input at this point; no assignment is done. 

d a decimal integer is expected; the corresponding argument should be an 

integer pointer. 

u an unsigned decimal integer is expected; the corresponding argument should 
be an unsigned integer pointer. 

o an octal integer is expected; the corresponding argument should be an integer 
pointer. 

x a hexadecimal integer is expected; the corresponding argument should be an 
integer pointer. 

e,f,g a floating point number is expected; the next field is converted accordingly 
and stored through the corresponding argument, which should be a pointer to 
a float. The input format for floating point numbers is an optionally signed 
string of digits, possibly containing a decimal point, followed by an optional 
exponent field consisting of an E or an e, followed by an optional +, —, or 
space, followed by an integer. 

s a character string is expected; the corresponding argument should be a char¬ 
acter pointer pointing to an array of characters large enough to accept the 
string and a terminating \0, which will be added automatically. The input 
field is terminated by a white-space character. 

c a character is expected; the corresponding argument should be a character 
pointer. The normal skip over white space is suppressed in this case; to read 
the next non-space character, use %le. If a field width is given, the 
corresponding argument should refer to a character array; the indicated 
number of characters is read. 

[ indicates string data and the normal skip over leading white space is 

suppressed. The left bracket is followed by a set of characters, which we will 
call the scanset, and a right bracket; the input field is the maximal sequence 
of input characters consisting entirely of characters in the scanset. The 
circumflex (*), when it appears as the first character in the scanset, serves as 
a complement operator and redefines the scanset as the set of all characters 
not contained in the remainder of the scanset string. There are some conven¬ 
tions used in the construction of the scanset. A range of characters may be 
represented by the construct first—last, thus [0123456789] may be expressed 
[0—9]. Using this convention, first must be lexically less than or equal to last, 
or else the dash will stand for itself. The dash will also stand for itself when¬ 
ever it is the first or the last character in the scanset. To include the right 
square bracket as an element of the scanset, it must appear as the first char¬ 
acter (possibly preceded by a circumflex) of the scanset, and in this case it 
will not be syntactically interpreted as the closing bracket. The correspond¬ 
ing argument must point to a character array large enough to hold the data 
field and the terminating \0, which will be added automatically. At least one 
character must match for this conversion to be considered successful. 


The conversion characters d, u, o, and x may be preceded by 1 or h to indicate that 
a pointer to long or to short rather than to int is in the argument list. Similarly, 
the conversion characters e, f, and g may be preceded by 1 to indicate that a pointer 
to double rather than to float is in the argument list. The 1 or h modifier is 
ignored for other conversion characters. 
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Scanf conversion terminates at EOF, at the end of the control string, or when an 
input character conflicts with the control string. In the latter case, the offending 
character is left unread in the input stream. 

Scanf returns the number of successfully matched and assigned input items; this 
number can be zero in the event of an early conflict between an input character and 
the control string. If the input ends before the first conflict or conversion, EOF is 
returned. 
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EXAMPLES 
The call: 


int i, n; float x; char name[50]; 
n = scanf ("%d%f%s", &i, &x, name); 


with the input line: 

25 54.32E—1 thompson 


will assign to n the value 3, to i the value 25, to x the value 5.432, and name will 
contain thompson\0. Or: 


int i; float x; char name[50]; 

(void) scanf ("%2d%f%*d %(0— 9]", &i, &x, name); 


with input: 

56789 0123 56a72 


will assign 56 to 789.0 to x, skip 0123, and place the string 56\0 in name. The 
next call to getchar (see getc( 3S)) will return a. 


SEE ALSO 

getc(3S), printf(3S), strtod(3C), strtol(3C). 


NOTE 

Trailing white space (including a new-line) is left unread unless matched in the con¬ 
trol string. 


DIAGNOSTICS 

These functions return EOF on end of input and a short count for missing or illegal 
data items. 
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BUGS 


The success of literal matches and suppressed assignments is not directly determin¬ 
able. 
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NAME 

setbuf, setvbuf — assign buffering to a stream 


SYNOPSIS 

^include <stdio.h> 

void setbuf (stream, buf) 

FILE ^stream; 
char *buf; 

int setvbuf (stream, buf, type, size) 
FILE ^stream; 
char *buf; 
int type, size; 


DESCRIPTION 

Setbuf may be used after a stream has been opened but before it is read or written. 
It causes the array pointed to by buf to be used instead of an automatically allo¬ 
cated buffer. If buf is the NULL pointer input/output will be completely unbuffered. 

A constant BUFSIZ, defined in the <stdio.h> header file, tells how big an array is 
needed: 


char buf [BUFSIZ]; 

Setvbuf may be used after a stream has been opened but before it is read or written. 

Type determines how stream will be buffered. Legal values for type (defined in 

stdio.h) are: 

JOFBF causes input/output to be fully buffered. 

JOLBF causes output to be line buffered; the buffer will be flushed when a new- 
line is written, the buffer is full, or input is requested. 

JONBF causes input/output to be completely unbuffered. If buf is not the NULL 
pointer, the array it points to will be used for buffering, instead of an 
automatically allocated buffer. Size specifies the size of the buffer to be 
used. The constant BUFSIZ in <stdio.h> is suggested as a good buffer 
size. If input/output is unbuffered, buf and size are ignored. By default, 
output to a terminal is line buffered and all other input/output is fully 
buffered. 


SEE ALSO 

fopen(3S), getc(3S), malloc(3C), putc(3S), stdio(3S). 
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DIAGNOSTICS 

If an illegal value for type or size is provided, setvbuf returns a non-zero value. Oth¬ 
erwise, the value returned will be zero. 



NOTE 

A common source of error is allocating buffer space as an “automatic” variable in a 
code block, and then failing to close the stream in the same block. 



2 


Icon International, Inc. 



STDIO (3S) 


STANDARD I/O LIBRARY 


STDIO (3S) 


NAME 

stdio — standard buffered input/output package 


SYNOPSIS 

^include <stdio.h> 

FILE *stdin, *stdout, *stderr; 


DESCRIPTION 

The functions described in the entries of sub-class 3S of this manual constitute an 
efficient, user-level I/O buffering scheme. The in-line macros getc(3S) and putc( 3S) 
handle characters quickly. The macros getchar and putcliar, and the higher-level 
routines fgetc, fgets, fprintf, fputc, /puts, fread, fscanf, fwrite, gets, getw, printf, puts, 
putw, and scanf all use or act as if they use getc and putc; they can be freely inter¬ 
mixed. 

A file with associated buffering is called a stream and is declared to be a pointer to a 
defined type FILE. Fopen{ 3S) creates certain descriptive data for a stream and 
returns a pointer to designate the stream in all further transactions. Normally, 
there are three open streams with constant pointers declared in the <stdio.h> 
header file and associated with the standard open files: 


stdin standard input file 

stdout standard output file 

stderr standard error file 


A constant NULL (0) designates a nonexistent pointer. 

An integer-constant EOF (—1) is returned upon end-of-file or error by most integer 
functions that deal with streams (see the individual descriptions for details). 

An integer constant BUFSIZ specifies the size of the buffers used by the particular 
implementation. 

Any program that uses this package must include the header file of pertinent macro 
definitions, as follows: 

^include <stdio.h> 
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The functions and constants mentioned in the entries of sub-class 3S of this manual 
are declared in that header file and need no further declaration. The constants and 
the following “functions” are implemented as macros (redeclaration of these names is 
perilous): getc, getchar, putc, putchar, Jerror, feof, clearerr, and fileno. 


SEE ALSO 

open(2), close(2), lseek(2), pipe(2), read(2), write(2), ctermid(3S), cuserid(3S), 
fclose(3S), ferror(3S), fopen(3S), fread(3S), fseek(3S), getc(3S), gets(3S), popen(3S), 
printf(3S), putc(3S), puts(3S), scanf(3S), setbuf(3S), system(3S), tmpfile(3S), 
tmpnam(3S), ungetc(3S). 


DIAGNOSTICS 

Invalid stream pointers will usually cause grave disorder, possibly including program 
termination. Individual function descriptions describe the possible error conditions. 
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NAME 

system — issue a shell command 


SYNOPSIS 

^include <stdio.h> 

int system (string) 
char ^string; 


DESCRIPTION 

System causes the string to be given to sh( 1) as input, as if the string had been typed 
as a command at a terminal. The current process waits until the shell has com¬ 
pleted, then returns the exit status of the shell. 


FILES 


/bin/sh 


SEE ALSO 

exec(2). 

sh(l) in the ICON/UXV User Reference Manual. 


DIAGNOSTICS 

System forks to create a child process that in turn exec’s /bin/sh in order to exe¬ 
cute string. If the fork or exec fails, system returns a negative value and sets errno. 


Icon International, Inc. 


1 



TMPFILE (3S) STANDARD I/O LIBRARY TMPFILE (3S) 

NAME 

tmpfile — create a temporary file 

SYNOPSIS 

^include <stdio.h> 

FILE *tmpfile () 


DESCRIPTION 

Tmpfile creates a temporary file using a name generated by tmpnam( 3S), and returns 
a corresponding FILE pointer. If the file cannot be opened, an error message is 
printed using perror(3C), and a NULL pointer is returned. The file will automatically 
be deleted when the process using it terminates. The file is opened for update 


SEE ALSO 

creat(2), unlink(2), fopen(3S), mktemp(3C), perror(3C), tmpnam(3S). 
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NAME 

tmpnam, tempnam — create a name for a temporary file 


SYNOPSIS 

^include <stdio.h> 

char *tmpnam (s) 
char *s; 

char *tempnam (dir, pfx) 
char *dir, *pfx; 


DESCRIPTION 

These functions generate file names that can safely be used for a temporary file. 

Tmpnam always generates a file name using the path-prefix defined as P_tmpdir in 
the <s<dio./i> header file. If s is NULL, tmpnam leaves its result in an internal static 
area and returns a pointer to that area. The next call to tmpnam will destroy the 
contents of the area. If s is not NULL, it is assumed to be the address of an array of 
at least L_tmpnam bytes, where Ljmpnam is a constant defined in <stdio.h >; 
tmpnam places its result in that array and returns s. Tempnam allows the user to 
control the choice of a directory. The argument dir points to the name of the direc¬ 
tory in which the file is to be created. If dir is NULL or points to a string which is 
not a name for an appropriate directory, the path-prefix defined as P_tmpdir in the 
<stdio.h> header file is used. If that directory is not accessible, /tmp will be used 
as a last resort. This entire sequence can be up-staged bv providing an environment 
variable TMPDIR in the user’s environment, whose value is the name of the desired 
temporary-file directory. Many applications prefer their temporary files to have cer¬ 
tain favorite initial letter sequences in their names. Use the pfx argument for this. 
This argument may be NULL or point to a string of up to five characters to be used 
as the first few characters of the temporary-file name. Tempnam uses malloc( 3C) to 
get space for the constructed file name, and returns a pointer to this area. Thus, 
any pointer value returned from tempnam may serve as an argument to free (see 
malloc{ 3C)). If tempnam cannot return the expected result for any reason, i.e. 
malloc( 3C) failed, or none of the above mentioned attempts to find an appropriate 
directory was successful, a NULL pointer will be returned. 


NOTES 

These functions generate a different file name each time they are called. Files 
created using these functions and either fopen( 3S) or creatf 2) are temporary only in 
the sense that they reside in a directory intended for temporary use, and their names 
are unique. It is the user’s responsibility to use unlink( 2) to remove the file when its 
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use is ended. 


SEE ALSO 

creat(2), unlink(2), fopen(3S), malloc(3C), mktemp(3C), tmpfile(3S). 


BUGS 


If called more than 17,576 times in a single process, these functions will start recy¬ 
cling previously used names. 

Between the time a file name is created and the file is opened, it is possible for some 
other process to create a file with the same name. This can never happen if that 
other process is using these functions or mktemp, and the file names are chosen so as 
to render duplication by other means unlikely. 


/t '\ 

( 
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NAME 

ungetc — push character back into input stream 


SYNOPSIS 

^include <stdio.h> 

int ungetc (c, stream) 
int c; 

FILE ^stream; 


DESCRIPTION 

Ungetc inserts the character c into the buffer associated with an input stream. That 
character, c, will be returned by the next getc(SS) call on that stream. Ungetc 
returns c, and leaves the file stream unchanged. 

One character of pushback is guaranteed, provided something has already been read 
from the stream and the stream is actually buffered. In the case that stream is 
stdin, one character may be pushed back onto the buffer without a previous read 
statement. 

If c equals EOF, ungetc does nothing to the buffer and returns EOF 
Fseek{ 3S) erases all memory of inserted characters. 


SEE ALSO 

fseek(3S), getc(3S), setbuf(3S). 


DIAGNOSTICS 

Ungetc returns EOF if it cannot insert the character. 
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NAME 

vprintf, vfprintf, vsprintf — print formatted output of a varargs argument list 


SYNOPSIS 

^include <stdio.h> 
#include <varargs.h> 

int vprintf (format, ap) 
char ^format; 
va_list ap; 


int vfprintf (stream, format, ap) 
FILE *stream; 
char *format; 
va_list ap; 


int vsprintf (s, format, ap) 
char *s, ^format; 
vajist ap; 


DESCRIPTION 

vprintf, vfprintf, and vsprintf are the same as printf, fprintf, and sprintf respectively, 
except that instead of being called with a variable number of arguments, they are 
called with an argument list as defined by varargs( 5). 


EXAMPLE 

The following demonstrates how vfprintf could be used to write an error routine. 

^include <stdio.h> 

^include <varargs.h> 


A 

* error should be called like 

* error(function_name, format, argl, arg2...); 

*/ 

/♦VARARGSO*/ 

void 

error(va_alist) 

/* Note that the function_name and format arguments cannot be 

* separately declared because of the definition of varargs. 

*/ 
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va_dcl 

{ 

vajlist args; 
char *fmt; 

va_start(args); 

/* print out name of function causing error */ 
(void)fprintf(stderr, "ERROR in %s: ", va_arg(args, char *)); 
fmt * va_arg(args, char *); 

/* print out remainder of message */ 

(void)vfprintf(fmt, args); 
va_end(args); 

(void)abort( ); 


SEE ALSO 

vprintf(3X), varargs(5). 
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NAME 

assert — verify program assertion 


SYNOPSIS 

^include <assert.h> 

assert (expression) 
int expression; 


DESCRIPTION 

This macro is useful for putting diagnostics into programs. When it is executed, if 
expression is false (zero), assert prints 


“Assertion failed: expression, file xyz, line nnn ” 


on the standard error output and aborts. In the error message, xyz is the name of 
the source file and nnn the source line number of the assert statement. 

Compiling with the preprocessor option — DNDEBUG (see cpp(l)), or with the prepro¬ 
cessor control statement “^define NDEBUG” ahead of the “#include <assert.h>” 
statement, will stop assertions from being compiled into the program. 


SEE ALSO 

abort(3C). 

cpp(l) in the ICON/UXV User Reference Manual. 
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NAME v.- 

curses — CRT screen handling and optimization package 


SYNOPSIS 

^include <curses.h> 

cc [ flags ] files —lcurses [ libraries ] 


DESCRIPTION 

These routines give the user a method of updating screens with reasonable optimiza¬ 
tion. In order to initialize the routines, the routine initscrf) must be called before 
any of the other routines that deal with windows and screens are used. The routine 
endwinf) should be called before exiting. To get character-at-a-time input without 
echoing, (most interactive, screen oriented-programs want this) after calling initscrf) 
you should call “nonlf); cbreakf); noecho();” 

The full curses interface permits manipulation of data structures called windows 
which can be thought of as two dimensional arrays of characters representing all or 
part of a CRT screen. A default window called stdscr is supplied, and others can be 
created with newwin. Windows are referred to by variables declared “WINDOW 
the type WINDOW is defined in curses.h to be a C structure. These data structures 
are manipulated with functions described below, among which the most basic are 
move, and addch. (More general versions of these functions are included with 
names beginning with ‘w’, allowing you to specify a window. The routines not begin¬ 
ning with ‘w’ affect stdscr.) Then refreshf) is called, telling the routines to make 
the users CRT screen look like stdscr. 


Mini-Curses is a subset of curses which does not allow’ manipulation of more than 
one window. To invoke this subset, use -DMINICURSES as a cc option. This level is 
smaller, and faster than full curses. 

If the environment variable TERMINFO is defined, any program using curses will 
check for a local terminal definition before checking in the standard place. For 
example, if the standard place is /usr/lib/terminfo, and TERM is set to “vtlOO”, 
then normally the compiled file is found in /usr/lib/terminfo/v/vtlOO. (The “v” 
is copied from the first letter of “vtlOO” to avoid creation of huge directories.) How¬ 
ever, if TERMINFO is set to /asr/mark/myterms, curses will first check 
/opusr/mark/myterms/v/vtlOO, and if that fails, will then check 
/usr/lib/terminfo/v/vtlOO. This is useful for developing experimental definitions 
or when write permission in /usr/lib/terminfo is not available. 

SEE ALSO 

terminfo(4). 
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FUNCTIONS 

Routines listed here may be called when using the full curses. Those marked with an 
asterisk may be called when using Mini-Curses. 


addch(ch)* 

addstr(str)* 
attroff(attrs)* 
attron(attrs)* 
attrset(attrs)* 
baudrate( )* 
beep( )* 

box(win, vert, hor) 


clear() 

clearok(win, bf) 
clrtobot() 
clrtoeol() 
cbreak( )* 
delay_output(ms)* 
delch() 
deleteln() 
delwin(win) 
doupdate() 
echo( )* 
endwin( )* 
erase() 
erasechar() 
fixterm() 
flash() 
flushinp( )* 
getch()* 
getstr(str) 
gettmode() 
getyx(win, y, x) 
has_ic() 
has_il() 
idlok(win, bf)* 
inch() 
initscr()* 
insch(c) 
insertln() 
intrflush(win, bf) 
keypad(win, bf) 
killchar() 
leaveok(win, flag) 


longname() 
meta(win, flag)* 


add a character to atdaer (like putchar) 

(wraps to next line at end of line) 

calls addch with each character in atr 

turn off attributes named 

turn on attributes named 

set current attributes to attrs 

current terminal speed 

sound beep on terminal 

draw a box around edges of win 

vert and hor are chars to use for vert, and 

hor. edges of box 

clear stdscr 

clear screen before next redraw of win 
clear to bottom of stdscr 
clear to end of line on stdscr 
set ebreak mode 

insert ms millisecond pause in output 
delete a character 
delete a line 
delete win 

update screen from all wnooutrefresh 
set echo mode 
end window modes 
erase stdaer 

return user’s erase character 

restore tty to "in curses” state 

flash screen or beep 

throw away any typeahead 

get a char from tty 

get a string through stdscr 

establish current tty modes 

get (y, x) co-ordinates 

true if terminal can do insert character 

true if terminal can do insert line 

use terminal’s insert/delete line if bf != 0 

get char at current (y, x) co-ordinates 

initialize screens 

insert a char 

insert a line 

interrupts flush output if bf is TRUE 

enable keypad input 

return current user’s kill character 

OK to leave cursor anywhere after refresh if 

flag!=0 for win f otherwise cursor must be left 

at current position. 

return verbose name of terminal 

allow meta characters on input if flag != 0 


Inc. 
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move(y, x)* move to (y, x) on $td$cr 

mvaddch(y, x, ch) move(y, x) then addch(ch) 

mvaddstr(y, x, str) similar.,. 

mvcur(oldrow, oldcol, iiewraw, newcol)iow level cursor motion 

mvdelch(y, x) like delch, but move(y, x) first 

mvgetch(y, x) etc. 

mvgetstr(y, x) 

mvinch(y, x) 

mvinsch(y, x, c) 

mvprintw(y, x, fmt, args) 

mvscanw(y, x, fmt, args) 

mvwaddch(win, y, x, ch) 

mvwaddstr(win, y, x, str) 

mvwdelch(win, y, x) 

mvwgetch(win, y, x) 

mvwgetstr(win, y, x) 

mvwin(win, by, bx) 

mvwinch(win, y, x) 

mvwinsch(win, y, x, c) 

mvwprintw(win, y, x, fmt, aTgs) 

mvwscanw(win, y, x, fmt, args) 

newpad(nlines, ncols) create a new pad with given dimensions 

newterm(type, fd) set up new terminal of given type to output on fd 

newwin(lines, cols, begin_y, begin_x) create a new window 
nl( )* set newline mapping 

nocbreak( )* unset cbreak mode 

nodelay(win, bf) enable nodelay input mode through getch 

noecho( )* unset echo mode 

nonl( )* unset newline mapping 

noraw( )* unset Taw mode 

overlay(winl, win2) overlay winl on win2 

overwrite(winl, win2) overwrite winl on top of win2 

pnoutrefresh(pad, pminrow, pmincol, sminrow, smincol, smaxrow, smaxcol) 

like prefresh but with no output until doupdate called 
prefresh(pad, pminrow, pmincol, sminrow, smincol, smaxrow, smaxcol) 

refresh from pad starting with given upper left corner of pad 
with output to given portion of screen 
printw(fmt, argl, arg2, ...)printf on atdztr 

raw( )* set raw mode 

refresh( )* make current screen look like stdscr 

resetterm( )* set tty modes to ’’out of curses’* state 

resetty( )* reset tty flags to stored value 

saveterm( )* save current modes as ”in curses” state 

savetty( )* store current tty flags 

scanw(fmt, argl, arg2, ~.)scanf through stdscr 

scroll(win) scroll win one line 

scrollok(win, flag) allow terminal to scroll if flag != 0 

set_term(new) now talk to terminal new 

setscrreg(t, b) set user scrolling region to lines t through b 

setterm(type) establish terminal with given type 

setupterm(term, filenum, errret) 

standend( )* clear standout mode attribute 

standout( )* set standout mode attribute 
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subwin(win, lines, cols, 
touchwin(win) 
traceoff() 
traceon() 
typeahead(fd) 
unctrl(ch)* 
waddch(win, ch) 
waddstr(win, str) 
wattroff(win, attrs) 
wattron(win, attrs) 
wattrset(win, attrs) 
wclear(win) 
wclrtobot(win) 
wclrtoeol(win) 
wdelch(win, c) 
wdeleteln(win) 
werase(win) 
wgetch(win) 
wgetstr(win, str) 
winch(win) 
winsch(win, c) 
winsertln(win) 
wmove(win, y, x) 
wnoutrefresh(win) 
wprintw(win, fmt, argl 
wrefresh(win) 
wscanw(win, fmt, argl, 
wsetscrreg(win, t, b) 
wstandend(win) 
wstandout(win) 


begin_y, begin_x) create a subwindow 
“change” all of win 
turn off debugging trace output 
turn on debugging trace output 
use file descriptor fd to check typeahead 
printable version of eh 
add char to win 
add string to win 
turn off attrs in win 
turn on attrs in win 
set attrs in win to attrs 
clear win 

clear to bottom of win 
clear to end of line on win 
delete char from win 
delete line from win 
erase win 

get a char through win 
get a string through win 
get char at current (y, x) in win 
insert char into win 
insert line into win 
set current (y, x) co-ordinates on win 
refresh but no screen output 
, arg2, ...) printf on win 
make screen look like win 
arg2, ...) scanf through win 
set scrolling region of win 
clear standout attribute in win 
set standout attribute in win 


TERMINFO LEVEL ROUTINES 

These routines should be called by programs wishing to deal directly with the ter- 
minfo database. Due to the low level of this interface, it is discouraged. Initially, 
setupterm should be called. This will define the set of terminal dependent variables 
defined in terminfo(4). The include files <curses.h> and <term.h> should be 
included to get the definitions for these strings, numbers, and flags. Parmeterized 
strings should be passed through tparm to instantiate them. All terminfo strings 
(including the output of tparm) should be printed with tputs or putp . Before exiting, 
resetterm should be called to restore the tty modes. (Programs desiring shell escapes 
or suspending with control Z can call resetterm before the shell is called and fixterm 
after returning from the shell.) 

fixterm() restore tty modes for terminfo use 

(called by setupterm) 

resetterm() reset tty modes to state before program entry 

setupterm(term, fd, rc) read in database. Terminal type is the 

character string term } all output is to ICON/UXV 
System file 

descriptor fd . A status value is returned in the 
integer pointed to by rc: 1 is normal. The simplest 
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call would be aetupterm(0, 1, 0) which uses all the defaults. 
tparm(str, pi, p2, p9)instantiate string str with parms pj. 
tputs(str, affcnt, putc) apply padding info to string etr. 

affent is the number of lines affected, or 1 if 
not applicable. Putc is a putchar-like function 
to which the characters are passed, one at a time. 
putp(str) handy function that calls tputs(str, 1, putchar). 

vidputs(attrs, putc) output the string to put terminal in video attribute 

mode attra, which is any combination of the attributes 
listed below. Chars are passed to putchar-like function putc. 
vidattr(attrs) Like vidputs but outputs through putchar 


TERMCAP COMPATIBILITY ROUTINES 

These routines were included as a conversion aid for programs that use termcap. 

Their parameters are the same as for termcap. They are emulated using the ter- 

minfo database. They may go away at a later date. 

tgetent(bp, name) look up termcap entry for name 

tgetflag(id) get boolean entry for id 

tgetnum(id) get numeric entry for id 

tgetstr(id, area) get string entry for id 

tgoto(cap, col, row) apply parms to given cap 

tputs(cap, affcnt, fn) apply padding to cap calling fn as putchar 


ATTRIBUTES 

The following video attributes can be passed to the functions attron,attroff,attrset. 

A_STANDOUT Terminal’s best highlighting mode 

AJUNDERLINE Underlining 

AJR.EVERSE Reverse video 

A_BLINK Blinking 

A.DIM Half bright 

A-BOLD Extra bright or bold 

A_BLANK Blanking (invisible) 

A_PROTECT Protected 

AALTCHARSET Alternate character set 


FUNCTION KEYS 

The following function keys might be returned by getch if keypad has been enabled. 
Note that not all of these are currently supported, due to lack of definitions in ter- 
minfo or the terminal not transmitting a unique code when the key is pressed. 


Name 

Value 

Key name 

KEY3REAK 

0401 

break key (unreliable) 

KEYJDOWN 

0402 

The four arrow keys .. 

KEY.UP 

0403 


IvEYJLEFT 

0404 


KEY_RIGHT 

0405 
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KEY_HOME 

0406 

Home key (upward+left arrow) 

KEY_BACKSPACE 

0407 

backspace (unreliable) 

KEYJFO 

0410 

Function keys. Space for 64 is reserved. 

KEY_F(n) 

(KEYJ'0-f(n))Formula for fn. 

KEYJDL 

0510 

Delete line 

KEYJL 

0511 

Insert line 

KEYJDC 

0512 

Delete character 

KEY_IC 

0513 

Insert char or enter insert mode 

KEY_EIC 

0514 

Exit insert char mode 

KEY.CLEAR 

0515 

Clear screen 

KEY_EOS 

0516 

Clear to end of screen 

KEY_EOL 

0517 

Clear to end of line 

KEYJSF 

0520 

Scroll 1 line forward 

KEY_SR 

0521 

Scroll 1 line backwards (reverse) 

KEY_NPAGE 

0522 

Next page 

KEY_PPAGE 

0523 

Previous page 

KEY_STAB 

0524 

Set tab 

KEY.CTAB 

0525 

Clear tab 

KEY_CATAB 

0526 

Clear all tabs 

KEY_ENTER 

0527 

Enter or send (unreliable) 

KEY_SRESET 

0530 

soft (partial) reset (unreliable) 

KEYJtESET 

0531 

reset or hard reset (unreliable) 

KEY_PRINT 

0532 

print or copy 

KEY_LL 

0533 

home down or bottom (lower left) 


WARNING 

The plotting library plot( 3X) and the curses library ct/rs«s(3X) both use the names 
erase() and move(). The curses versions are macros. If you need both libraries, put 
the plot( 3X) code in a different source file than the curses( 3X) code, and/or #undef 
move() and erase() in the plot( 3X) code. 
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NAME 

directory: opendir, readdir, telldir, seekdir, rewinddir, closedir — directory operations 


SYNOPSIS 

^include <sys/types.h> 
^include <dirent.h> 

DIR *opendir(filename) 
char ^filename; 

struct dirent *readdir (dirp) 
DIR *dirp; 

long telldir (dirp) 

DIR *dirp; 

void seekdir (dirp, loc) 

DIR *dirp; 
long loc; 

void rewinddir (dirp) 

DIR *dirp; 

void closedir (dirp) 

DIR *dirp; 


DESCRIPTION 

Opendir opens the directory named by filename and associates a directory stream 
with it. Opendir returns a pointer to be used to identify the directory stream in sub¬ 
sequent operations. The pointer NULL is returned if filename cannot be accessed, or 
is not a directory, or if it cannot malloc( 3X) enough memory to hold a DIR structure 
or a buffer for the directory entries. 

Readdir returns a pointer to the next directory entry. No inactive entries are 
returned. It returns NULL upon reaching the end of the directory or upon detecting 
an invalid location in the directory. 


Telldir returns the current location associated with the named directory stream. 

Seekdir sets the position of the next readdir operation on the directory stream. The 
new position reverts to the one associated with the directory stream when the telldir 
operation from which loc was obtained was performed. Values returned by telldir 
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are good only if the directory has not changed due to compaction or expansion. 

Rewinddir resets the position of the named directory stream to the beginning of the 
directory. 

Closedir closes the named directory stream and frees the DIR structure. 

The following errors can occur as a result of these operations. 
opendir: 

[ENOTDIR] A component of filename is not a directory. 

[EACCES] A component of filename denies search permission. 

[EMFILE] Filename points outside the allocated address space. 


readdir: 

[ENOENTJ The current file pointer for the directory is not located at a valid 

entry. 

[EBADF] The file descriptor determined by the DIR stream is no longer valid. 

This results if the DIR stream has been closed. 


telldir, seekdir, and closedir: 

[EBADF] The file descriptor determined by the DIR stream is no longer valid. 

This results if the DIR stream has been closed. 


EXAMPLE 

Sample code which searches a directory for entry name: 


d i rp as opend i r ("«**) ; 

uh i I e ( (dp = readd i r ( d i rp U ! = NULL ) 

if ( etrcep (dp->d_naee, naee ) as 0 ) 4 

cIosedir( dirp ) j 
return FOUND; 

} 

cIosedir ( dirp ); 
return N0T_F0UND; 


2 


Icon International, Inc. 


DIRECTORY (3X) MISCELLANEOUS FUNCTIONS DIRECTORY (3X) 

WARNINGS 

Rewinddir is implementd as a macro, so its function address cannot be taken. 
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NAME 


Idahread — read the archive header of a member of an archive file 


SYNOPSIS 

#include <stdio.h> 
#include <ar.h> 
#include <filehdr.h> 
#include <ldfcn.h> 


int Idahread (Idptr, arhead) 
LDFELE *ldptr; 

ARCHDR *arhead; 


DESCRIPTION 

If TYPE (Idptr) is the archive file magic number, Idahread reads the archive header of 
the common object file currently associated with Idptr into the area of memory 
beginning at arhead. 

Ldahread returns SUCCESS or FAILURE. Ldahread will fail if TYPE (Idptr) does 
not represent an archive file, or if it cannot read the archive header. 

The program must be loaded with the object file access routine library iibld.a. 

SEE ALSO 

ldclose(3X), ldopen(3X), ldfcn(4), ar(4). 
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NAME 

ldclose, ldaclose — close a common object file 


SYNOPSIS 

^include <stdio.h> 
#include <filehdr.h> 
#in elude <ldfcn.h> 


int ldclose (Idptr) 
LDFILE *ldptr; 

int ldaclose (Idptr) 
LDFILE *ldptr; 


DESCRIPTION 

Ldopen( 3X) and ldclose are designed to provide uniform access to both simple object 
files and object files that are members of archive files. Thus an archive of common 
object files can be processed as if it were a series of simple common object files. 

If TYPE (Idptr) does not represent an archive file, ldclose will close the file and free 
the memory allocated to the LDFILE structure associated with Idptr. If 
TYPE (Idptr) is the magic number of an archive file, and if there are any more files in 
the archive, ldclose will reinitialize OFFSET(/dp<r) to the file address of the next 
archive member and return FAILURE. The LDFILE structure is prepared for a sub¬ 
sequent ldopen( 3X). In all other cases, ldclose returns SUCCESS. 

Ldaclose closes the file and frees the memory allocated to the LDFILE structure 
associated with Idptr regardless of the value of TYPE (Idptr). Ldaclose always 
returns SUCCESS. The function is often used in conjunction with Idaopen. 

The program must be loaded with the object file access routine library libld.a. 

SEE ALSO 

fclose(3S), ldopen(3X), ldfcn(4). 
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NAME 

ldfhread — read the file header of a common object file 


SYNOPSIS 

^include <stdio.h> 
#include <filehdr.h> 
^include <ldfcn.h> 


int ldfhread (ldptr, filehead) 
LDFILE * ldptr; 

FELHDR *filehead; 


DESCRIPTION 

Ldfhread reads the file header of the common object file currently associated with 
ldptr into the area of memory beginning at filehead. 

Ldfhread returns SUCCESS or FAILURE. Ldfhread will fail if it cannot read the file 
header. 

In most cases the use of ldfhread can be avoided by using the macro HEADER(/rfp<r) 
defined in ldfcn.h (see ldfcn (4)). The information in any field, fieldname, of the file 
header may be accessed using HEADER(ldptr).fieldname. 

The program must be loaded with the object file access routine library libld.a. 

SEE ALSO 

ldclose(3X), ldopen(3X), ldfcn(4). 
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NAME 


ldgetname — retrieve symbol name for common object file symbol table entry 


SYNOPSIS 

^include <stdio.h> 

#inelude <filehdr.h> 

^include <syms.h> 

#inciude <ldfcn.h> 

char *ldgetname (ldptr, symbol) 
LDFILE *ldptr; 

SYMENT *symbol; 


DESCRIPTION 

Ldgetname returns a pointer to the name associated with symbol as a string. The 
string is contained in a static buffer local to ldgetname that is overwritten by each 
call to ldgetname, and therefore must be copied by the caller if the name is to be 
saved. 

As of UNIX System V Release 2.0, the common object file format has been extended 
to handle arbitrary length symbol names with the addition of a “string table”. 
Ldgetname will return the symbol name associated with a symbol table entry for 
either a pre- UNIX System V Release 2.0 object file or a UNIX System V Release 2.0 
object file. Thus, ldgetname can be used to retrieve names from object files without 
any backward compatibility problems. Ldgetname will return NULL (defined in 
stdio.h) for an object file if the name cannot be retrieved. This situation can occur: 

— if the “string table” cannot be found, 

— .if not enough memory can be allocated for the string table, 

— if the string table appears not to be a string table (for example, if an auxili¬ 
ary entry is handed to ldgetname that looks like a reference to a name in a 
non-existent string table), or 

— if the name’s offset into the string table is past the end of the string table. 

Typically, ldgetname will be called immediately after a successful call to Idtbread to 
retrieve the name associated with the symbol table entry filled by Idtbread. 

The program must be loaded with the object file access routine library libld.a. 

SEE ALSO 

ldclose(3X), ldopen(3X), ldtbread(3X), ldtbseek(3X), ldfcn(4). 
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NAME 

ldlread, ldlinit, ldlitem — manipulate line number entries of a common object file 
function 


SYNOPSIS 

^include <stdio.h> 
#in elude <filehdr.h> 
#in elude <linenum.h> 
^include <ldfcn.h> 


int ldlread(ldptr, fcnindx, linenum, linent) 

LDFILE *ldptr; 

long fcnindx; 

unsigned short linenum; 

LINENO linent; 

int ldlinit(ldptr, fcnindx) 

LDFILE *ldptr; 
long fcnindx; 

int ldlitem(ldptr, linenum, linent) 

LDFILE *ldptr; 
unsigned short linenum; 

LINENO linent; 


DESCRIPTION 

Ldlread searches the line number entries of the common object file currently associ¬ 
ated with Idptr. Ldlread begins its search with the line number entry for the begin¬ 
ning of a function and confines its search to the line numbers associated with a single 
function. The function is identified by fcnindx, the index of its entry in the object 
file symbol table. Ldlread reads the entry with the smallest line number equal to or 
greater than linenum into linent. 

Ldlinit and ldlitem together perform exactly the same function as ldlread. After an 
initial call to ldlread or ldlinit, ldlitem may be used to retrieve a series of line number 
entries associated with a single function. Ldlinit simply locates the line number 
entries for the function identified by fcnindx. Ldlitem finds and reads the entry with 
the smallest line number equal to or greater than linenum into linent. 

Ldlread, ldlinit, and ldlitem each return either SUCCESS or FAILURE. Ldlread will 
fail if there are no line number entries in the object file, if fcnindx does not index a 
function entry in the symbol table, or if it finds no line number equal to or greater 
than linenum. Ldlinit will fail if there are no line number entries in the object file or 
if fcnindx does not index a function entry in the symbol table. Ldlitem will fail if it 
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finds no line number equal to or greater than linenum. 

The programs must be loaded with the object file access routine library libld.a. 

SEE ALSO 

ldclose(3X), ldopen(3X), ldtbindex(3X), ldfcn(4). 
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NAME 

ldlseek, ldnlseek — seek to line number entries of a section of a common object file 


SYNOPSIS 

^include <stdio.h> 
#include <filehdr.h> 
#include <ldfcn.h> 

int ldlseek (ldptr, sectindx) 
LDFBLE * ldptr; 
unsigned short sectindx; 


int ldnlseek (ldptr, sectname) 
LDFELE *ldptr; 
char *sectname; 


DESCRIPTION 

Ldlseek seeks to the line number entries of the section specified by sectindx of the 
common object file currently associated with ldptr. 

Ldnlseek seeks to the line number entries of the section specified by sectname. 

Ldlseek and ldnlseek return SUCCESS or FAILURE. Ldlseek will fail if sectindx is 
greater than the number of sections in the object file; ldnlseek will fail if there is no 
section name corresponding with *sectname. Either function will fail if the specified 
section has no line number entries or if it cannot seek to the specified line number 
entries. 

Note that the first section has an index of one. 

The program must be loaded with the object file access routine library libld.a. 


SEE ALSO 

ldclose(3X), ldopen(3X), ldshread(3X), ldfcn(4). 
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X. X 

NAME ^ 

ldohseek — seek to the optional file header of a common object file 


SYNOPSIS 

^include <stdio.h> 
#include <filehdr.h> 
#include <ldfcn.h> 

int ldohseek (ldptr) 
LDFILE * ldptr; 


DESCRIPTION 

Ldohseek seeks to the optional file header of the common object file currently associ¬ 
ated with ldptr. 

Ldohseek returns SUCCESS or FAILURE. Ldohseek will fail if the object file has no 
optional header or if it cannot seek to the optional header. 

The program must be loaded with the object file access routine library libld.a. 


SEE ALSO 

ldclose(3X), ldopen(3X), ldfhread(3X), ldfcn(4). 
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NAME 

ldopen, ldaopen — open a common object file for reading 


SYNOPSIS 

^include <stdio.h> 
^include <filehdr.h> 
^include <ldfcn.h> 


LDFILE *ldopen (filename, ldptr) 
char ^filename; 

LDFILE *ldptr; 

LDFILE *ldaopen (filename, oldptr) 
char ^filename; 

LDFILE *oldptr; 


DESCRIPTION 

Ldopen and ldclose(SX) are designed to provide uniform access to both simple object 
files and object files that are members of archive files. Thus an archive of common 
object files can be processed as if it were a series of simple common object files. 

If ldptr has the value NULL, then ldopen will open filename and allocate and initial¬ 
ize the LDFILE structure, and return a pointer to the structure to the calling pro¬ 
gram. 


If ldptr is valid and if TYPE (ldptr) is the archive magic number, ldopen will reinitial¬ 
ize the LDFILE structure for the next archive member of filename. 

Ldopen and ldclose( 3X) are designed to work in concert. Ldclose will return 
FAILURE only when TYPE (ldptr) is the archive magic number and there is another 
file in the archive to be processed. Only then should ldopen be called with the 
current value of ldptr. In all other cases, in particular whenever a new filename is 
opened, ldopen should be called with a NULL ldptr argument. 

The following is a prototype for the use of ldopen and ldclose( 3X). 


/* for each filename to be processed */ 


ldptr = NULL; 
do 
{ 


Icon International, Inc. 


1 



LD0PEN(3X) 


MISCELLANEOUS FUNCTIONS 


LDOPEN (3X) 


if ((ldptr = ldopen(filename, ldptr)) != NULL ) 

/* check magic number */ 

/* process the file */ 

} while (ldclose(ldptr) = FAILURE ); 


If the value of oldptr is not NULL, Idaopen will open filename anew and allocate and 
initialize a new LDFILE structure, copying the TYPE, OFFSET, and HEADER 
fields from oldptr. Ldaopen returns a pointer to the new LDFILE structure. This 
new pointer is independent of the old pointer, oldptr. The two pointers may be used 
concurrently to read separate parts of the object file. For example, one pointer may 
be used to step sequentially through the relocation information, while the other is 
used to read indexed symbol table entries. 

Both Idopen and Idaopen open filename for reading. Both functions return NULL if 
filename cannot be opened, or if memory for the LDFILE structure cannot be allo¬ 
cated. A successful open does not insure that the given file is a common object file 
or an archived object file. 


The program must be loaded with the object file access routine library libld.a. 


SEE ALSO 

fopen(3S), ldclose(3X), ldfcn(4). 
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NAME 

ldrseek, ldnrseek — seek to relocation entries of a section of a common object file 


SYNOPSIS 

^include <stdio.h> 
^include <filehdr.h> 

#in elude <ldfcn.h> 

int ldrseek (ldptr, sectindx) 
LDFILE *ldptr; 
unsigned short sectindx; 


int ldnrseek (ldptr, sectname) 
LDFILE *ldptr; 
char *sectname; 


DESCRIPTION 

Ldrseek seeks to the relocation entries of the section specified by sectindx of the com¬ 
mon object file currently associated with ldptr. 

Ldnrseek seeks to the relocation entries of the section specified by sectname. 

Ldrseek and ldnrseek return SUCCESS or FAILURE. Ldrseek will fail if sectindx is 
greater than the number of sections in the object file; ldnrseek will fail if there is no 
section name corresponding with sectname. Either function w'ill fail if the specified 
section has no relocation entries or if it cannot seek to the specified relocation 
entries. 

Note that the first section has an index of one. 

The program must be loaded with the object file access routine library libld.a. 

SEE ALSO 

ldclose(3X), ldopen(3X), ldshread(3X), ldfcn(4). 
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NAME 

ldshread, ldnshread — read an indexed/named section header of a common object file 


SYNOPSIS 

#include <stdio.h> 
#include <filehdr.h> 
^include <scnhdr.h> 
^include <ldfcn.h> 


int ldshread (Idptr, sectindx, secthead) 
LDFELE *ldptr; 
unsigned short sectindx; 

SCNHDR *secthead; 

int ldnshread (Idptr, sectname, secthead) 
LDFILE *ldptr; 
char *sectname; 

SCNHDR *secthead; 


DESCRIPTION 

Ldshread reads the section header specified by sectindx of the common object file 
currently associated with Idptr into the area of memory beginning at secthead. 

Ldnshread reads the section header specified by sectname into the area of memory 
beginning at secthead. 

Ldshread and ldnshread return SUCCESS or FAILURE. Ldshread will fail if sectindx 
is greater than the number of sections in the object file; ldnshread will fail if there is 
no section name corresponding with sectname. Either function will fail if it cannot 
read the specified section header. 

Note that the first section header has an index of one. 

The program must be loaded with the object file access routine library libld.a. 

SEE ALSO 

ldclose(3X), ldopen(3X), ldfcn(4). 
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NAME 

ldsseek, Idnsseek — seek to an indexed/named section of a common object file 


SYNOPSIS 

^include <stdio.h> 

^include <filehdr.h> 
^include <ldfcn.h> 

int ldsseek (ldptr, sectindx) 
LDFILE *ldptr; 
unsigned short sectindx; 

int Idnsseek (ldptr, sectname) 
LDFILE *ldptr; 
char *sectname; 


DESCRIPTION 

Ldsseek seeks to the section specified by sectindx of the common object file currently 
associated with ldptr. 

Ldnsseek seeks to the section specified by sectname. 

Ldsseek and Idnsseek return SUCCESS or FAILURE. Ldsseek will fail if sectindx is 
greater than the number of sections in the object file; Idnsseek will fail if there is no 
section name corresponding with sectname. Either function will fail if there is no 
section data for the specified section or if it cannot seek to the specified section. 

Note that the first section has an index of one. 

The program must be loaded with the object file access routine library libld.a. 


SEE ALSO 

ldclose(3X), ldopen(3X), ldshread(3X), ldfcn(4). 
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NAME 

ldtbindex — compute the index of a symbol table entry of a common object file 


SYNOPSIS 

^include <stdio.h> 
#include <filebdr.h> 
^include <syms.h> 
^include <ldfcn.h> 


long ldtbindex (ldptr) 
LDFELE *ldptr; 


DESCRIPTION 

Ldtbindex returns the (long) index of the symbol table entry at the current position 
of the common object file associated with ldptr. 


The index returned by ldtbindex may be used in subsequent calls to ldtbread( 3X). 
However, since ldtbindex returns the index of the symbol table entry that begins at 
the current position of the object file, if ldtbindex is called immediately after a par¬ 
ticular symbol table entry has been read, it will return the index of the next entry. 

Ldtbindex will fail if there are no symbols in the object file, or if the object file is not 
positioned at the beginning of a symbol table entry. 

Note that the first symbol in the symbol table has an index of zero. 

The program must be loaded with the object file access routine library libld.a. 


SEE ALSO 

ldclose(3X), ldopen(3X), ldtbread(3X), ldtbseek(3X), ldfcn(4). 
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NAME 

ldtbread — read an indexed symbol table entry of a common object file 


SYNOPSIS 

#include <stdio.h> 

^include <filehdr.h> 

#include <syms.h> 

#include <ldfcn.h> 

int ldtbread (ldptr, symlndex, symbol) 
LDFILE *ldptr; 
long symindex; 

SYMENT *symbol; 


DESCRIPTION 

Ldtbread reads the symbol table entry specified by symindex of the common object 
file currently associated with ldptr into the area of memory beginning at symbol. 

Ldtbread returns SUCCESS or FAILURE. Ldtbread will fail if symindex is greater 
than the number of symbols in the object file, or if it cannot read the specified sym¬ 
bol table entry. 

Note that the first symbol in the symbol table has an index of zero. 

The program must be loaded with the object file access routine library libld.a. 


SEE ALSO 

ldclose(3X), ldopen(3X), ldtbseek(3X), ldgetname(3X), ldfcn(4). 
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NAME 

ldtbseek — seek to the symbol table of a common object file 



SYNOPSIS 

^include <stdio.h> 
^include <filehdr.h> 
#include <ldfcn.h> 

int ldtbseek (ldptr) 
LDFELE *ldptr; 


DESCRIPTION 

Ldtbseek seeks to the symbol table of the object file currently associated with ldptr. 

Ldtbseek returns SUCCESS or FAILURE. Ldtbseek will fail if the symbol table has 
been stripped from the object file, or if it cannot seek to the symbol table. 

The program must be loaded with the object file access Toutine library libld.a. 


SEE ALSO 

ldclose(3X), ldopen(3X), ldtbread(3X), ldfcn(4). 


f %. 
(" 
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NAME 

logname — return login name of user 


SYNOPSIS 

char *logname( ) 


DESCRIPTION 

Logname returns a pointer to the null-terminated login name; it extracts the SLOG- 
NAME variable from the user’s environment. 

This routine is kept in /lib/libPW.a. 


FILES 


/etc/profile 


SEE ALSO 

profile(4), environ(5). 

env(l), login(l) in the ICON/UXV User Reference Manual. 


BUGS 


The return values point to static data whose content is overwritten by each call. 
This method of determining a login name is subject to forgery. 
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NAME 

malloc, free, realloc, calloc, mallopt, mallinfo — fast main memory allocator 


SYNOPSIS 

^include <malloc.h> 
char *malloc (size) 
unsigned size; 

void free (ptr) 
char *ptr; 

char *realloc (ptr, size) 
char *ptr; 
unsigned size; 

char *calloc (nelem, elsize) 
unsigned nelem, elsize; 

int mallopt (cmd, value) 
int cmd, value; 

struct mallinfo mallinfo (max) 
int max; 


DESCRIPTION 

Malloc and free provide a simple general-purpose memory allocation package, which 
runs considerably faster than the malloc{ZC ) package. It is found in the library 
“malloc”, and is loaded if the option lmalloc” is used with cc(l) or ld( 1). 

Malloc returns a pointer to a block of at least size bytes suitably aligned for any use. 

The argument to free is a pointer to a block previously allocated by malloc ; after 
free is performed this space is made available for further allocation, and its contents 
have been destroyed (but see mallopt below for a way to change this behavior). 


Undefined results will occur if the space assigned by malloc is overrun or if some ran¬ 
dom number is handed to free. 

Realloc changes the size of the block pointed to by ptr to size bytes and returns a 
pointer to the (possibly moved) block. The contents will be unchanged up to the 
lesser of the new and old sizes. 
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Calloc allocates space for an array of nelem elements of size elsize. The space is ini¬ 
tialized to zeros. 


Mallopt provides for control over the allocation algorithm. The available values for 
cmd are: 

M_MXFAST Set maxfast to value. The algorithm allocates all blocks below the size 
of maxfast in large groups and then doles them out very quickly. The 
default value for maxfast is 0. 

M_NLBLKS Set numlblks to value. The above mentioned “large groups” each con¬ 
tain numlblks blocks. Numlblks must be greater than 0. The default 
value for numlblks is 100. 


M_GRAIN Set grain to value. The sizes of all blocks smaller than maxfast are con¬ 
sidered to be rounded up to the nearest multiple of grain. Grain must 
be greater than 0. The default value of grain is the smallest number of 
bytes which will allow alignment of any data type. Value will be 
rounded up to a multiple of the default when grain is set. 

M_KEEP Preserve data in a freed block until the next malloc, realloc, or calloc. 

This option is provided only for compatibility with the old version of 
malloc and is not recommended. 


These values are defined in the <malloc.h> header file. 


Mallopt may be called repeatedly, but may not be called after the first small block is 
allocated. 


Mallinfo provides instrumentation describing space usage. It returns the structure: 


struct mallinfo { 
int arena; 
int ordblks; 
int smblks; 
int hblkhd; 
int hblks; 
int usmblks; 
int fsmblks; 
int uordblks; 
int fordblks; 
int keepcost; 


} 


/* total space in arena */ 

/* number of ordinary blocks */ 

/* number of small blocks */ 

/* space in holding block headers */ 
/* number of holding blocks */ 

/* space in small blocks in use */ 

/* space in free small blocks */ 

/* space in ordinary blocks in use */ 
/* space in free ordinary blocks */ 

/* space penalty if keep option */ 

/* is used */ 


This structure is defined in the <malloc.h> header file. 


Each of the allocation routines returns a pointer to space suitably aligned (after pos¬ 
sible pointer coercion) for storage of any type of object. 
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SEE ALSO 

brk(2), malloc(3C). 


DIAGNOSTICS 

Malloc, realloc and calloc return a NULL pointer if there is not enough available 
memory. When realloc returns NULL, the block pointed to by ptr is left intact. If 
mallopt is called after any allocation or if cmd or value are invalid, non-zero is 
returned. Otherwise, it returns zero. 


WARNINGS 

This package usually uses more data space than malloc{ZC). 

The code size is also bigger than malloc( 3C). 

Note that unlike malloc{ 3C), this package does not preserve the contents of a block 
when it is freed, unless the M_KEEP option of mallopt is used. 

Undocumented features of malloc( 3C) have not been duplicated. 


Icon International, Inc. 


3 



PL0T(3X) 


MISCELLANEOUS FUNCTIONS 


PLOT (3X) 


NAME 

plot — graphics interface subroutines 


SYNOPSIS 

openpl () 

erase () 

label (s) 
char *s; 

line (xl, yl, x2, y2) 
int xl, yl, x2, y2; 

circle (x, y, r) 
int x, y, r; 

arc (x, y, xO, yO, xl, yl) 
int x, y, xO, yO, xl, yl; 

move (x, y) 
int x, y; 

cont (x, y) 
int x, y; 

point (x, y) 
int x, y; 


linemod (s) 
char *s; 

space (xO, yO, xl, yl) 
int xO, yO, xl, yl; 

closepl() 


DESCRIPTION 

These subroutines generate graphic output in a relatively device-independent 
manner. Space must be used before any of these functions to declare the amount of 
space necessary. See plot(4). Openpl must be used before any of the others to open 
the device for writing. Closepl flushes the output. 
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Circle draws a circle of radius r with center at the point (x, y). 

Arc draws an arc of a circle with center at the point (x, y) between the points (xO, 
yO) and (x1, yl). 

String arguments to label and linemod are terminated by nulls and do not contain 
new-lines. 

See plot{ 4) for a description of the effect of the remaining functions. 

The library files listed below provide several flavors of these routines. 


FILES 


/usr/lib/libplot.a 
/usr/lib/lib300.a 
/ usr /lib /lib300s.a 
/usr /lib /lib450.a 
/ usr /lib/lib4014 .a 


produces output for tplot{ 1G) filters 
for DASI 300 
for DASI 300s 

for DASI 450 
for TEKTRONK 4014 


WARNINGS 

In order to compile a program containing these functions in file.c it is necessary to 
use “cc file.c —lplot”. 


In order to execute it, it is necessary to use “a.out { tplot”. 


The above routines use <stdio.h>, which causes them to increase the size of pro¬ 
grams, not otherwise using standard I/O, more than might be expected. 


SEE ALSO 

plot(4). 

graph(lG), stat(lG), tplot(lG) in the ICON/UXV User Reference Manual. 


9 


Icon International, Inc. 



REGCMP (3X) 


MISCELLANEOUS FUNCTIONS 


REGCMP (3X) 


NAME 

regcmp, regex — compile and execute regular expression 


SYNOPSIS 

char *regcmp (stringl [, string2, ...], (char *)0) 
char *stringl, *string2, .. 

char *regex (re, subject^ retO, ...]) 
char *re, ^subject, *retO, ...; 

extern char *_loci; 


DESCRIPTION 

Regcmp compiles a regular expression and returns a pointer to the compiled form. 
Malloc(3C) is used to create space for the vector. It is the user’s responsibility to 
free unneeded space so allocated. A NULL return from regcmp indicates an incorrect 
argument. Regcmp{ 1) has been written to generally preclude the need for this rou¬ 
tine at execution time. 

Regex executes a compiled pattern against the subject string. Additional arguments 
are passed to receive values back. Regex returns NULL on failure or a pointer to the 

next unmatched character on success. A global character pointer _ loci points to 

where the match began. Regcmp and regex were mostly borrowed from the editor, 
ed( 1); however, the syntax and semantics have been changed slightly. The following 
are the valid symbols and their associated meanings. 

[] * .* These symbols retain their current meaning. 

$ Matches the end of the string; \n matches a new-line. 

— Within brackets the minus means through. For example, [a—z] is 

equivalent to [abed.. .xyz]. The — can appear as itself only if used as the 
first or last character. For example, the character class expression []—] 
matches the characters ] and —. 

-I- A regular expression followed by + means one or more times. For example, 

P-9]+ is equivalent to [0—9][0—9]*. 

{m} {m,} {m,u} 

Integer values enclosed in {} indicate the number of times the preceding 
regular expression is to be applied. The value m is the minimum number 
and u is a number, less than 256, which is the maximum. If only m is 
present (e.g., {m}), it indicates the exact number of times the regular 
expression is to be applied. The value {m,} is analogous to {m,infinity}. 
The plus (+) and star (*) operations are equivalent to {1,} and {0,} respec¬ 
tively. 

( ... )$n The value of the enclosed regular expression is to be returned. The value 
will be stored in the (n-+l) th argument following the subject argument. At 
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most ten enclosed regular expressions are allowed. Regex makes its assign¬ 
ments unconditionally. 

( ... ) Parentheses are used for grouping. An operator, e.g., *, +, {}, can work on 
a single character or a regular expression enclosed in parentheses. For 
example, (a*(cb+)*)$0. 

By necessity, all the above defined symbols are special. They must, therefore, be 
escaped to be used as themselves. 


EXAMPLES 

Example 1: 

char *cursor, *newcursor, *ptr; 

newcursor = regex((ptr = regcmp("*\n", 0)), cursor); 
free(ptr); 


This example will match a leading new-line in the subject string pointed at by cur¬ 
sor. 


Example 2: 

char ret0[9]; 

char *newcursor, *name; 

name = regcmp("([A—Za— z][A— za—zO—9_]{0,7})$0", 0); 
newcursor = regex(name, "123Testing321", retO); 


This example will match through the string “Testing3” and will return the address 
of the character after the last matched character (cursor+ll). The string “Test- 
ing3” will be copied to the character array retO. 

Example 3: 

#include "file.i" 

char *string, *newcursor; 

newcursor = regex(name, string); 


This example applies a precompiled regular expression in file.i (see regcmp( 1)) 
against string. 

This routine is kept in /lib/libPW.a. 
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SEE ALSO 

malloc(3C). 

ed(l), regcmp(l) in the ICON/UXV User Reference Manual. 


BUGS 


The user program may run out of memory if regcmp is called iteratively without 
freeing the vectors no longer required. The following user-supplied replacement for 
malloc( 3C) reuses the same vector saving time and space: 

/* user’s program */ 

char * 
malloc(n) 
unsigned n; 

{ 

static char rebuf[512]; 

return (n <= sizeof rebuf) ? rebuf : NULL; 

} 
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NAME 

sputl, sgetl — access long integer data in a machine-independent fashion. 


SYNOPSIS 

void sputl (value, buffer) 
long value; 
char ^buffer; 

long sgetl (buffer) 
char ^buffer; 


DESCRIPTION 

Sputl takes the four bytes of the long integer value and places them in memory start¬ 
ing at the address pointed to by buffer. The ordering of the bytes is the same across 
all machines. 

Sgetl retrieves the four bytes in memory starting at the address pointed to by buffer 
and returns the long integer value in the byte ordering of the host machine. 

The combination of sputl and sgetl provides a machine-independent way of storing 
long numeric data in a file in binary form without conversion to characters. 

A program which uses these functions must be loaded with the object-file access rou¬ 
tine library libld.a. 
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NAME 

vprintf, vfprintf, vsprintf — print formatted output of a varargs argument list 


SYNOPSIS 

^include <stdio.h> 

^include <varargs.h> 

int vprintf (format, ap) 
char ^format; 
va_list ap; 

int vfprintf (stream, format, ap) 
FILE ^stream; 
char *format; 
va_list ap; 

int vsprintf (s, format, ap) 
char *s, ^format; 
va_list ap; 


DESCRIPTION 

vprintf. vfprintf , and vsprintf are the same as printf, fprintf, and sprintf respectively, 
except that instead of being called with a variable number of arguments, they are 
called with an argument list as defined by varargs( 5). 


EXAMPLE 

The following demonstrates how vfprintf could be used to write an error routine. 

#include <stdio.h> 

#include <varargs.h> 


/* 

* error should be called like 

* error(function_name, format, argl, arg2...); 

*/ 

/♦VARARGSO*/ 

void 

error(va_alist) 

/* Note that the function_name and format arguments cannot be 

* separately declared because of the definition of varargs. 

*/ 
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va_dcl 

{ 

va_list args; 
char *fmt; 

va_start(args); 

/* print out name of function causing error */ 
(void)fprintf(stderr, "ERROR in %s: ", va_arg(args, char *)); 
fmt = va_arg(args, char *); 

/* print out remainder of message */ 

(void)vfprintf(fmt, args); 
va_end(args); 

(void)abort( ); 


SEE ALSO 

printf(3S), varargs(5). 
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NAME 

intro — introduction to file formats 


DESCRIPTION 

This section outlines the formats of various files. The C struct declarations for the 
file formats are given where applicable. Usually, these structures can be found in the 
directories /usr/include or /usr/include/sys. 

References of the type name(lM) refer to entries found in Section 1 of the ICON/UXV 
Administrator Reference Manual. 
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NAME 

a.out — common assembler and link editor output 


DESCRIPTION 

The file name a.out is the output file from the assembler os(l) and the link editor 
ld( 1). Both programs will make a.out executable if there were no errors in assem¬ 
bling or linking and no unresolved external references. 


A common object file consists of a file header, a UNIX system header, a table of sec¬ 
tion headers, relocation information, (optional) line numbers, a symbol table, and a 
string table. The order is given below. 


File header. 

UNIX system header. 
Section 1 header. 

Section n header. 
Section 1 data. 

Section n data. 

Section 1 relocation. 

Section n relocation. 
Section 1 line numbers. 

Section n line numbers. 
Symbol table. 

String table. 


The last three parts of an object file (line numbers, symbol table, and string table) 
may be missing if the program was linked with the —s option of ld{ 1) or if they were 
removed by strip( 1). Also note that the relocation information will be absent if there 
were no unresolved external references after linking. The string table exists only if 
the symbol table contains symbols with names longer than eight characters. 

The sizes of each section (contained in the header, discussed below) are in bytes and 
are even. 


When an a.out file is loaded into memory for execution, three logical segments are 
set up: the text segment, the data segment (initialized data followed by uninitialized, 
the latter actually being initialized to all 0’s), and a stack. On ICON computers the 
text segment starts at location 0 in the core image. The a.out file produced by ld( 1) 
by default has a number called the magic number 0410 in the first field of the UNIX 
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system header. The headers (file header, UNIX system header, and section headers) 
are loaded at the beginning of the text segment and the text immediately follows the 
headers in the user address space. The first text address will equal the size of the 
headers, and will vary depending upon the number of section headers in the a.out 
file. 


In an a.out file with three sections (.text, .data, and .bss), the first text address is at 
0. The text segment is not writable by the program; if other processes are executing 
the same a.out file, the processes will share a single text segment. 

The data segment starts at the next page boundary past the last text address. 


The stack begins at the high end of memory (0x40000000) and grows toward lower 
addresses. The stack is automatically extended as required. The data segment is 
extended only as requested by the brk(2) system call. 


The value of a word in the text or data portions that is not a reference to an 
undefined external symbol is exactly the value that will appear in memory when the 
file is executed. If a word in the text involves a reference to an undefined external 
symbol, the storage class of the symbol-table entry for that word will be marked as 
an “external symbol”, and the section number will be set to 0. When the file is pro¬ 
cessed by the link editor and the external symbol becomes defined, the value of the 
symbol will be added to the word in the file. 

File Header 

The format of the filehdr header is 


struct filehdr 

{ 

unsigned short 

unsigned short 

long 

long 

long 

unsigned short 
unsigned short 


f_magic; 

f_nscns; 

f_timdat; 

f_symptr; 

f_nsyms; 

f_opthdr; 

Lflags; 


/* magic number */ 

/* number of sections */ 

/* time and date stamp */ 
/* file ptr to symtab */ 

/* # symtab entries */ 

/* sizeof(opt hdr) */ 

/* flags */ 


UNIX System Header 

The format of the UNIX system header is 


typedef struct aouthdr 

{ 

short magic; 
short vstamp; 
long tsize; 


/* magic number */ 

/* version stamp */ 

/* text size in bytes, padded */ 
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long 

dsize; 

long 

bsize; 

long 

entry; 

long 

text_start; 

long 

data_start; 


} AOUTHDR; 


Section Header 

The format of the section header is 


/* initialized data (.data) */ 

/* uninitialized data (.bss) */ 

/* entry point */ 

/* base of text used for this file */ 
/* base of data used for this file */ 


struct scnhdr 

{ 

char 

long 

long 

long 

long 

long 

long 

unsigned 

unsigned 

long 

}; 


short 

short 


s_name[SYMNMLEN];/* section name */ 
s_paddr; /* physical address */ 

s_vaddr; /* virtual address */ 

s_size; /* section size */ 

s_scnptr; /* file ptr to raw data */ 
s_relptr; /* file ptr to relocation */ 
s_lnnoptr; /* file ptr to line numbers */ 
s_nreloc; /* # reloc entries */ 

s_nlnno; /* # line number entries */ 

s_flags; /* flags */ 


Relocation 

Object files have one relocation entry for each relocatable reference in the text or 
data. If relocation information is present, it will be in the following format: 


struct reloc 

{ 

long 

long 

short 

}; 


r_vaddr; 

r_symndx; 

r_type; 


/* (virtual) address of reference */ 
/* index into symbol table */ 

/* relocation type */ 


The start of the relocation information is s^relptr from the section header. If there 
is no relocation information, s_relptr is 0. 


Symbol Table 

The format of each symbol in the symbol table is 
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#define SYMNMLEN 8 

#define FJLNMLEN 14 

#define SYMESZ 18 /* the size of a SYMENT */ 


struct syment 

{ 


union 

{ 

char 

struct 


{ 

long 
long 
} -Q-n; 
char 
}-«; 

unsigned long 
short 

unsigned short 

char 

char 

}; 


/* get a symbol name */ 
_n_name[SYMNMLEN]; /* name of symbol */ 


_n_zeroes; /* = OL if in string table */ 
_n_offset; /* location in string table */ 

*_n_nptr[2]; /* allows overlaying */ 


n_value; 

n_scnum; 

n_type; 

n_sclass; 

n_numaux; 


/* value of symbol */ 

/* section number */ 

/* type and derived type */ 
/* storage class */ 

/* number of aux entries */ 


#define n_name 
^define n_zeroes 
^define n_offset 
^define n_nptr 


_n._n_name 

_n._n_n._n_zeroes 

_n._n_n._n_offset 

_n._n_nptr[l] 


Some symbols require more information than a single entry; they are followed by 
auxiliary entries that are the same size as a symbol entry. The format follows. 


union auxent { 
struct { 

long 


union { 


x_tagndx; 
struct { 
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}; 


unsigned short x_lnno; 
unsigned short x_size; 

} x_Jnsz; 
long x_fsize; 

} x_misc; 
union { 

struct { 

long xjnnoptr; 
long x_endndx; 

} x_fcn; 
struct { 

unsigned short x_dimen[DIMNUM]; 

} x_ary; 

} x_fcnary; 

unsigned short x_tvndx; 

} x_sym; 

struct { 

char x_fname[FILNMLEN]; 

} x_file; 


struct { 

long x_scnlen; 
unsigned short x_nreloc; 
unsigned short x_nlinno; 
} x_scn; 


struct { 

long x_tvfill; 

unsigned short x_tvlen; 
unsigned short x_tvran[2j; 

} x_tv; 


Indexes of symbol table entries begin at zero. The start of the symbol table is 
f_symptr (from the file header) bytes from the beginning of the file. If the symbol 
table is stripped, Jsymptr is 0. The string table (if one exists) begins at f_symptr 4- 
{f-nsyms * SYMESZ) bytes from the beginning of the file. 


SEE ALSO 

brk(2), filehdr(4), ldfcn(4), linenum(4), reloc(4), scnhdr(4), syms(4). 
as(l), cc(l), ld(l) in the ICON/UXV User Reference Manual. 
Common Object File Format in the ICON/UXV User Guide.. 
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NAME 

acct — per-process accounting file format 


SYNOPSIS 

#include <sys/acct.h> 


DESCRIPTION 

Files produced as a result of calling acct( 2) have records in the form defined by 
<sys/acct.h>, whose contents are: 

typedef ushort comp_t; /* "floating point" */ 

/* 13-bit fraction, 3-bit exponent */ 


struct 

{ 


}; 


acct 



char 

acjflag; 

/* Accounting flag */ 

char 

ac_stat; 

/* Exit status */ 

ushort 

ac_uid; 

ushort 

ac_gid; 


dev_t 

ac_tty; 


time_t 

ac_btime; 

/* Beginning time */ 

comp_t. 

ac_utime; 

/* acctng user time in clock ticks */ 

comp_t 

ac_jstime; 

/* acctng system time in clock ticks */ 

comp_t 

ac_etime; 

/* acctng elapsed time in clock ticks */ 

comp_t 

acjnem; 

/* memory usage in clicks */ 

comp_t 

ac_io; 

/* chars trnsfrd by read/write */ 

comp_t 

ac_rw; 

/* number of block reads/writes */ 

char 

ac_comm[8]; 

/* command name */ 


extern struct acct 
extern struct inode 


acctbuf; 

♦acctp; /* inode of accounting file */ 


#define AFORK 01 
#define ASU 02 
#define ACCTF 0300 


/* has executed fork, but no exec */ 
/* used super-user privileges */ 

/* record type: 00 = acct */ 


In ac_Jlag, the AFORK flag is turned on by each fork( 2) and turned off by an exec( 2). 
The ac_comm field is inherited from the parent process and is reset by any exec. 
Each time the system charges the process with a clock tick, it also adds to ac_mem 
the current process size, computed as follows: 

(data size) + (text size) / (number of in-core processes using text) 

The value of ac_mem/(ac_stime + ac_utime) can be viewed as an approximation to 
the mean process size, as modified by text-sharing. 
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The structure tacct.h, which resides with the source files of the accounting com¬ 
mands, represents the total accounting format used by the various accounting com¬ 
mands: 


/* 

* total accounting (for acct period), also for day 

*/ 


struct tacct { 

uid_t ta_uid; 

char ta_name[8]; 

float ta_cpu[2]; 

float ta_kcore[2]; 

float ta_con[2]; 

float ta_du; 

long ta_pc; 

unsigned short ta_sc; 
unsigned short ta_dc; 
unsigned short ta_fee; 

}; 


/* userid */ 

/* login name */ 

/* cum. cpu time, p/np (mins) */ 

/* cum kcore-minutes, p/np */ 

/* cum. connect time, p/np, mins */ 
/* cum. disk usage */ 

/* count of processes */ 

/* count of login sessions */ 

/* count of disk samples */ 

/* fee for special services */ 


SEE ALSO 

acct(2), exec(2), fork(2). 

acct(lM) in the ICON/UXV Administrator Reference Manual. 
acctcom(l) in the ICON/UXV USER Reference Manual. 


BUGS 


The flc_mem value for a short-lived command gives little information about the 
actual size of the command, because ac_mem may be incremented while a different 
command (e.g., the shell) is being executed by the process. 
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NAME 

ar — common archive file format 


DESCRIPTION 

The archive command ar(l) is used to combine several files into one. Archives are 
used mainly as libraries to be searched by the link editor ld( 1). 

Each archive begins with the archive magic string. 

#define ARMAG "!<arch>\n" /* magic string */ 

#define SARMAG 8 /* length of magic string */ 


Each archive which contains common object files (see a.out( 4)) includes an archive 
symbol table. This symbol table is used by the link editor ld( 1) to determine which 
archive members must be loaded during the link edit process. The archive symbol 
table (if it exists) is always the first file in the archive (but is never listed) and is 
automatically created and/or updated by or. 


Following the archive magic string are the archive file members. Each file member is 
preceded by a file member header which is of the following format: 


#define ARFMAG "‘\n" /* header trailer string */ 


struct ar_hdr 
{ 

char ar_name[l6]; 
char ar_date[l2]; 
char ar_uid|6l; 
char ar_gid[6]; 
char ar_mode[8]; 
char ar_size[10]; 
char ar_fmag[2]; 

}> 


/* file member header */ 

/* ’/’ terminated file member name */ 
/* file member date */ 

/* file member user identification */ 

/* file member group identification */ 
/* file member mode (octal) */ 

/* file member size */ 

/* header trailer string */ 


All information in the file member headers is in printable ASCII The numeric infor¬ 
mation contained in the headers is stored as decimal numbers (except for ar_mode 
which is in octal). Thus, if the archive contains printable files, the archive itself is 
printable. 


The ar^name field is blank-padded and slash (/) terminated. The ar^date field is the 
modification date of the file at the time of its insertion into the archive. Common 
format archives can be moved from system to system as long as the portable archive 
command ar(l) is used. Conversion tools such as arcr(l) and convert(l) exist to aid 
in the transportation of non-common format archives to this format. 


Icon International, Inc. 


1 



AR(4) 


FILE FORMATS 


AR(4) 


Each archive file member begins on an even byte boundary; a newline is inserted 
between files if necessary. Nevertheless the size given reflects the actual size of the 
file exclusive of padding. 

Notice there is no provision for empty areas in an archive file. 

If the archive symbol table exists, the first file in the archive has a zero length name 
(i.e., ar_name[0] = ’/’). The contents of this file are as follows: 

• The number of symbols. Length: 4 bytes. 

• The array of offsets into the archive file. Length: 4 bytes * “the number of 
symbols”. 

• The name string table. Length: ar_si>e — (4 bytes * (“the number of sym¬ 
bols” + 1)). 

The number of symbols and the array of offsets are managed with sgetl and sputl. 
The string table contains exactly as many null terminated strings as there are ele¬ 
ments in the offsets array. Each offset from the array is associated with the 
corresponding name from the string table (in order). The names in the string table 
are all the defined global symbols found in the common object files in the archive. 
Each offset is the location of the archive header for the associated symbol. 


SEE ALSO 

sputl(3X), a.out(4). 

ar(l), arcv(l), convert(l), ld(l), strip(l) in the ICON/UXV User Reference Manual. 


CAVEATS 

The common archive structure is not compatible between the PDP-11 and the IBM-370, 
due to the different file formats. See arcv(l) and convert(l) to convert between 
machines. 


Strip(l) will remove all archive symbol entries from the header. The archive symbol 
entries must be restored via the ts option of the ar(l) command before the archive 
can be used with the link editor ld( 1). 
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NAME 

checklist — list of file systems processed by fsck 


DESCRIPTION 

Checklist resides in directory /etc and contains a list of, at most, 15 special file 
names. Each special file name is contained on a separate line and corresponds to a 
file system. Each file system will then be automatically processed by the /scfc(lM) 
command. 


SEE ALSO 

fsck(lM) in the ICON/UXV Administrator Reference Manual. 
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NAME 

core — format of memory image file 


SYNOPSIS 

^include <machine/param.h> 
#include <sys/user.h> 
#include <sys/proc.h> 


DESCRIPTION 

The ICON/UXV System writes out a memory image of a terminated process when 
any of various errors occur. See $ignal(2) for the list of reasons; the most common 
are memory violations, illegal instructions, bus errors, and user-generated quit sig¬ 
nals. The memory image is called ‘core’ and is written in the process’s working 
directory (provided it can be; normal access controls apply). 

The maximum size of a core file is limited by ulimit[2). Files which would be larger 
than the limit are not created. 

The core file consists of the u. area, whose size (in bytes) is defined by the UBYTES 
manifest in the <.machine/param.li> file. The u. area starts with a user structure 
as given in <sys/user.h>. The remainder of the core file consists of the supervisor 
stack area, whose size is given (in bytes) by the SUPERSTACKSIZE manifest in the 
<.machine/param.h> file, the proc structure, whose size is given (in bytes) by the 
PROCSIZE manifest in the Kmachinefparam.h^ file, the data pages and then the 
stack pages of the process image. The amount of data space image in the core file is 
given (in bytes) by the variables p_segmap[DATA_SEG].segsize + 
p_segmap[BSSjSEG].segsize in the proc area. If the program that produced the core 
was an OMAGIC program, the data size will include the text size, 
psegmap[TEXT_SEG].segsize, also from the proc area (this segment will precede the 
data segments). The amount of stack image in the core file is given (in bytes) by the 
variable p_segmap[STACI£_SEG].segsize in the proc area. 

In general the debugger sd6(l) is sufficient to deal with core images. 


SEE ALSO 

sdb(l), signal(2), ulimit(2) 
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NAME 

cpio — format of cpio archive 


DESCRIPTION 

The header structure, when the —c option of cpt'o(l) is not used, is: 
struct { 

short h_magic, 

h_dev; 

ushort h_ino, 

h_mode, 
h_uid, 
h—gid; 

short h_nlink, 

h_rdev, 
h_mtime[2], 
h_namesize, 
h_filesize[2]; 

char h_name[h_namesize rounded to word]; 

} Hdr; 


When the —c option is used, the header information is described by: 


sscanf(Chdr,"%6o%6o%6o%6o%6o%6o%6o%6o%l llo%6o%lllo%s", 

<&Hdr.h_magic, &Hdr.h_dev, &Hdr.h_ino, &Hdr.h_mode, 
&Hdr.h_uid, &Hdr.h_gid, &Hdr.h_nlink, &Hdr.h_rdev, 
&Longtime, &Hdr.h_namesize,&Longfile,Hdr.h_name); 


Longtime and Longfile are equivalent to Hdr.h_mtime and Hdr.h_Jilesize, respec¬ 
tively. The contents of each file are recorded in an element of the array of varying 
length structures, archive, together with other items describing the file. Every 
instance of tumagic contains the constant 070707 (octal). The items h_dev through 
h_mtime have meanings explained in stat( 2). The length of the null-terminated path 
name h_name, including the null byte, is given by h_namesize. 

The last record of the archive always contains the name TRAILER!!!. Special files, 
directories, and the trailer are recorded with h^filesize equal to zero. 


SEE ALSO 

stat(2). 

cpio(l), find(l) in the ICON/UXV User Reference Manual. 
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NAME 

dir — format of directories 


SYNOPSIS 

^include <sys/types.h> 
^include <sys/dir.h> 


DESCRIPTION 

A directory behaves exactly like an ordinary file, save that no user may write into a 
directory. The fact that a file is a directory is indicated by a bit in the flag word of 
its i-node entry; see fs(4). The structure of a directory entry as given in the include 
file is: 

/* 

* A directory consists of some number of blocks of DIRBLKSIZ 

* bytes, where DIRBLKSIZ is chosen such that it can be transferred 

* to disk in a single atomic operation (e.g. 512 bytes on most machines). 

* 

* Each DIRBLKSIZ byte block contains some number of directory entry 

* structures, which are of variable length. Each directory entry has 

* a struct direct at the front of it, containing its inode number, 

* the length of the entry, and the length of the name contained in 

* the entry. These are followed by the name padded to a 4 byte boundary 

* with null bytes. All names are guaranteed null terminated. 

* The maximum length of a name in a directory is MAXNAMLEN. 

* 

* The macro DIRSIZ(dp) gives the amount of space required to represent 

* a directory entry. Free space in a directory is represented by 

* entries which have dp->d_reclen > DIRSIZ(dp). All DIRBLKSIZ bytes 

* in a directory block are claimed by the directory entries. This 

* usually results in the last entry in a directory having a large 

* dp->d_reclen. When entries are deleted from a directory, the 

* space is returned to the previous entry in the same directory 

* block by increasing its dp->d_reclen. If the first entry of 

* a directory block is free, then its dp->d_ino is set to 0. 

* Entries other than the first in a directory do not normally have 

* dp->d_ino set to 0. 

*/ 

#ifdef KERNEL 

#define DIRBLKSIZ DEVJBSIZE 

•^clsc 

#define DIRBLKSIZ 512 
#endif 

#define MAXNAMLEN 255 

/* 
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* The DIRSIZ macro gives the minimum record 

* length which will hold the directory entry. 

* This requires the amount of space in struct 

* direct without the d_name field, plus enough 

* space for the name with a terminating null 

* byte (dp->d_namlen+l), rounded up to a 4 

* byte boundary. 

*/ 

#undef DIRSIZ 

#define DIRSIZ(dp) \ 

((sizeof (struct direct) * (MAXNAMLEN+1)) + 
(((dp)->d_namlen+l + 3) 3)) 

struct direct { 

ujong d_ino; 

short d_reclen; 

short d_namlen; 

char d_name[MAXNAMLEN 4- l]; 

/* typically shorter */ 

struct _dirdesc { 

int dd_fd; 

long dd_loc; 

long dd_size; 

char dd_buf[DIRBLKSIZ]; 

}> 


By convention, the first two entries in each directory are for V and The first is 
an entry for the directory itself. The second is for the parent directory. The mean¬ 
ing of is modified for the root directory of the master file system (“/”)> where 
has the same meaning as 

The library calls opendir, readdir, telldir, seekdir, rewinddir and closedir are provided 
to manipulate directory entries. 


SEE ALSO 

fs(4), directory(3x) 
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NAME 

dosdisks — list of MPS/DOS virtual disks 


DESCRIPTION 

The file /etc/dosdisks contains a list of the pathnames for all files to be used as 
vdisks for MPS/DOS. The files are created by dosdisk(8) and each new file path¬ 
name is appended to /etc/dosdisks by dosdisk. The vdisks are accessed in the order in 
which they appear in / etc/dosdisks; the order the filenames appear may be changed 
to cause the vdisks to have different MPS/DOS assignments. To delete a vdisk, 
remove the MPS/UX file, then edit /etc/dosdisks and remove the line specifying the 
deleted vdisk. The space for the deleted vdisk will be be reclaimed when MPS/UX is 
rebooted. Removing a ‘d’ partition vdisk is somewhat more involved; contact Icon 
for further assistance. 


The first disk to appear should always be bootable, or MPS/DOS will be unable to 
initialize. See ’’Technical Note on Dose and Proc/286 Support” for full details of 
vdisk support. 


FILES 


/etc/dosprinters 


See Also 

dosdisk(lM), Technical Note on Dose, SMILE Users Manual 


Icon International, Inc. 


1 



DOSPRINTERS (4) 


FILE FORMATS 


DOSPRINTERS (4) 


NAME 

dosprinters — destinations for spooled output from SLPT printers 


DESCRIPTION 

The file /etc/dosprinters is read by the dosprint program and specifies destination 
and options for the SLPT printers used under MPS/DOS. It contains zero or more 
lines in the following format: 

n pr [opt] 

where "n" is the SLPT printer number (0-7), "pr” is the printer name lpr(l) is to use 
for printing, and "[opt]" is an optional string which is passed to lpr which can be 
used to set various modes. For example, 

1 lp 
3 lp -p 
7 laser3 

specifies that the output from SLPTl should be spooled to "lp" (this is actually the 
default); the output from SLPT3 is spooled to "lp" with the -p flag (which causes lpr 
to pass the file through the "pr" filter); and the output from SLPT7 is spooled to a 
printer known as "laser3". Notice that it is not necessary to specify an entry for all 
8 printers; all SLPT devices default to "lp" with no options. 


FILES 


/etc/dosprinters 


See Also 

lp(l), Technical Note on Dose 
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NAME 

dstrules — Daylight savings time and time zone name rule file. 


DESCRIPTION 

The dstrules file contains a set of rules for daylight savings time, and time zone 
names. This allows for modification of daylight savings time rules or time zone 
names without recompilation. Upon its initial invocation in any process, the 
ctime(S) library routine reads the dstrules configuration file for a set of rules. If none 
are found, it uses a default table of rules which are current as of April 1, 1987. 

Comments begin with a and are ended with the end of the line. Fields must be 
separated by tabs. 

Each rule begins with %R and must be ended with a lambda which is an impossible 
date in the future, for example 9999. In a rule, offset is the number of hours time is 
to be shifted during daylight savings time. Hemisphere is one of N or S denoting the 
northern or southern hemispheres, respectively. The parameter yeareffective is the 
year that begins the period during which daylight savings time is in effect between 
startday and endday. Let us consider the following example of a rule definition: 


%R 

1 

N 

1970 

119 

303 

1974 

5 

333 

1975 

58 

303 

1976 

119 

303 

1987 

96 

303 

9999 

0 

0 


In the example shown above, from 1790 to 1973 daylight savings time begins on the 
Sunday, closest to the 119TH day and ends on the Sunday closes to the 303 rd day. 
During 1974, daylight savings time begins on or about the 5 TR day and ends on or 
about the 333 rd day, and so forth. 


The time zone name definition section begins with %Z. If you use %Z more than 
once in your dstrules file, the table may not be parsed correctly, and the default 
tables compiled into timezone(S) will be used. In a time zone name, minuteswest is 
the number of minutes west of GMT for that zone. Standardname is the name for 
the zone when no daylight savings time is in effect, and dstname is the name for the 
zone when daylight savings time is in effect. The entry for a zone name is inter¬ 
preted as a null string. If you use a null string for dstname when daylight savings 
time is in effect, timezone(S) may become confused, and create its own string. 


BUGS 
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The daylight savings time rules for parts of Europe are not confirmed. 

Daylight savings time must begin on a Sunday. 

It is not possible to give more than one timezone name to a particular offset from 
GMT without the rule file parser becoming extreemly confused. 


FILES 


/etc/dstrules 


SEE ALSO 

ctime(3), date(l) 


2 


Icon International, Inc. 



FILEHDR (4) 


FILE FORMATS 


FILEHDR (4) 


NAME 

filehdr — file header for common object files 


SYNOPSIS 

#include <filehdr.h> 


DESCRIPTION 

Every common object file begins with a 20-byte header. The following C struct 
declaration is used: 


struct filehdr 

{ 

unsigned short 

unsigned short 

long 

long 

long 

unsigned short 
unsigned short 

}; 


f_magic ; 
f_nscns ; 
f_timdat ; 
f_symptr ; 
f_nsyms ; 
f_opthdr ; 
f_flags ; 


/* magic number */ 

/* number of sections */ 
/* time & date stamp */ 
/* file ptr to symtab */ 
/* # symtab entries */ 
/* sizeof(opt hdr) */ 

/* flags */ 


F^symptr is the byte offset into the file at which the symbol table can be found. Its 
value can be used as the offset in fseek(3S) to position an I/O stream to the symbol 
table. The UNIX system optional header is 28 bytes. The valid magic numbers are 
given below: 


#define MC68MAGIC 0521 /♦2k page version */ 


The value in f_timdat is obtained from the time( 2) system call. Flag bits currently 
defined are: 


#define FJtELFLG 00001 
#define F_EXEC 00002 
#define F_LNNO 00004 
#define F_LSYMS 00010 
#define FJvGNMAL 00020 
^define FJJPDATE 00040 
#define FJSWABD 00100 
#define F_AR16WR 00200 
#define F^R32WTl 00400 
#define F^lR 32W 01000 
#define F_PATCH 02000 


/* relocation entries stripped */ 
/* file is executable */ 

/* line numbers stripped */ 

/* local symbols stripped */ 

/* minimal object file */ 

/* update file, ogen produced */ 
/* file is "pre-swabbed" */ 

/* 16 bit DEC host */ 

/* 32 bit DEC host */ 

/* non-DEC host */ 

/* "patch" list in opt hdr */ 
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time(2), fseek(3S), a.out(4). 
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NAME 

fs — format of file system volume 


SYNOPSIS 

^include <sys/types.h> 
^include <sys/fa.h> 
^include <sys/inode.h> 


DESCRIPTION 

Every file system storage volume (disk, nine-track tape, for instance) has a common 
format for certain vital information. Every such volume is divided into a certain 
number of blocks. The block size is a parameter of the file system. Sectors 0 to 15 
on a file system are used to contain primary and secondary bootstrapping programs. 

The actual file system begins at sector 16 with the super block. The layout of the 
super block as defined by the include file <sys/f$.h> is: 

#define FS_MAGIC 0x011954 

struct fs { 

struct fs *fs_link; /* linked list of file systems */ 

struct fs *fs_rlink; /* used for incore super blocks */ 

daddr_t fs_sblkno; /* addr of super-block in filesys */ 

daddr_t fs_cblkno; /* offset of cyl-block in filesys */ 

daddr_t fs_iblkno; /* offset of inode-blocks in filesys */ 

daddr_t fs_dblkno; /* offset of first data after eg */ 

long fs_cgoffset; /* cylinder group offset in cylinder */ 

long fs_cgmask; /* used to calc mod fs_ntrak */ 

time_t fs_time; /* last time written */ 

long fs_size; /* number of blocks in fs */ 

long fs_dsize; /* number of data blocks in fs */ 

long fs_ncg; /* number of cylinder groups */ 

long fs_bsize; /* size of basic blocks in fs */ 

long fs_fsize; /* size of frag blocks in fs */ 

long fs_frag; /* number of frags in a block in fs */ 

/* these are configuration parameters */ 

long fs_minfree; /* minimum percentage of free blocks */ 

long fs_rotdelay; /* num of ms for optimal next block */ 

long fs_rps; /* disk revolutions per second */ 

/* these fields can be computed from the others */ 

long fs__bmask; /* “blkoff” calc of blk offsets */ 

long fs_fmask; /* “fragoff” calc of frag offsets */ 

long fs_bshift; /* “lblkno” calc of logical blkno */ 

long fs_fshift; /* “numfrags” calc number of frags */ 

/* these are configuration parameters */ 

long fs_maxcontig; /* max number of contiguous blks */ 

long fs_maxbpg; /* max number of blks per cvl group */ 
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long 

fs_fragshift; 

long 

fs_fsbtodb; 

long 

fs_jsbsize; 

long 

fs_csmask; 

long 

fs_csshift; 

long 

fs_nindir; 

long 

fsjinopb; 

long 

fs_nspf; 

long 

fs_sparecon[6]; 


/* these fields can be computed from the others */ 

/* block to frag shift */ 

/* fsbtodb and dbtofsb shift constant */ 
/* actual size of super block */ 

/* csum block offset */ 

/* csum block number */ 

/* value of NINDIR */ 

/* value of INOPB */ 

/* value of NSPF */ 

/* reserved for future constants */ 

/* sizes determined by number of cylinder groups and their sizes */ 
daddr_t fs_csaddr; /* blk addr of cyl grp summary area */ 

long fs_cssize; /* size of cyl grp summary area */ 

long fs_cgsize; /* cylinder group size */ 

/* these fields should be derived from the hardware */ 

long fs_ntrak; /* tracks per cylinder */ 

long fs_nsect; /* sectors per track */ 

long fs_spc; /* sectors per cylinder */ 

/* this comes from the disk driver partitioning */ 

long fs_ncyl; /* cylinders in file system */ 

/* these fields can be computed from the others */ 


long 

fs_cpg; 

/* cylinders per group */ 

long 

fsJpg; 

/* inodes per group */ 

long 

fs_fpg; 

/* blocks per group * fs_frag */ 


/* this data must be re-computed after crashes */ 

struct csum fs_cstotal;/* cylinder summary information */ 
/* these fields are cleared at mount time */ 

char fs_fmod; /* super block modified flag */ 

char fs_clean; /* file system is clean flag */ 

char fs_ronly; /* mounted read-only flag */ 

char fsjflags; /* currently unused flag */ 

char fs_fsmnt; /* name mounted on */ 

[MAXMNTLEN] 

/* these fields retain the current block allocation info */ 
long fs_cgrotor; /* last eg searched */ 

struct csum *fs_csp; /* list of fs_cs info buffers */ 

[MAXCSBUFS] 

long fs_cpc; /* cyl per cycle in postbl */ 

short fs_postbl; /* head of blocks for each rotation */ 

[MAXCPG] [NRPOS] 

long fs_magic; /* magic number */ 

u_char fs_rotbl[l|; /* list of blocks for each rotation */ 


(* actually longer */ 


Each disk drive contains some number of file systems. A file system consists of a 
number of cylinder groups. Each cylinder group has inodes and data. 

A file system is described by its super-block, which in turn describes the cylinder 
groups. The super-block is critical data and is replicated in each cylinder group to 
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protect against catastrophic loss. This is done at file system creation time and the 
critical super-block data does not change, so the copies need not be referenced 
further unless disaster strikes. 

Addresses stored in inodes are capable of addressing fragments of ‘blocks’. File sys¬ 
tem blocks of at most size MAXBSIZE can be optionally broken into 2, 4, or 8 pieces, 
each of which is addressable; these pieces may be DEVJBSIZE, or some multiple of a 
DEV_BSIZE unit. 

Large files consist of exclusively large data blocks. To avoid undue wasted disk 
space, the last data block of a small file is allocated as only as many fragments of a 
large block as are necessary. The file system format retains only a single pointer to 
such a fragment, which is a piece of a single large block that has been divided. The 
size of such a fragment is determinable from information in the inode, using the 
“blksize(fs, ip, lbn)” macro. 

The file system records space availability at the fragment level; to determine block 
availability, aligned fragments are examined. 

The root inode is the root of the file system. Inode 0 can’t be used for normal pur¬ 
poses and historically bad blocks were linked to inode 1, thus the root inode is 2 
(inode 1 is no longer used for this purpose, however numerous dump tapes make this 
assumption, so we are stuck with it). The lost+found directory is given the next 
available inode when it is initially created by mkfs. 

fs_minfree gives the minimum acceptable percentage of file system blocks which may 
be free. If the freelist drops below this level only the super-user may continue to allo¬ 
cate blocks. This may be set to 0 if no reserve of free blocks is deemed necessary, 
however severe performance degradations will be observed if the file system is run at 
greater than 90% full; thus the default value of fs_minfree is 10%. 

Empirically the best trade-off between block fragmentation and overall disk utiliza¬ 
tion at a loading of 90% comes with a fragmentation of 4, thus the default fragment 
size is a fourth of the block size. 

Cylinder group related limits : Each cylinder keeps track of the availability of blocks 
at different rotational positions, so that sequential blocks can be laid out with 
minimum rotational latency. NRPOS is the number of rotational positions which 
are distinguished. With NRPOS 8 the resolution of the summary information is 2ms 
for a typical 3600 rpm drive. 

fs^rotdelay gives the minimum number of milliseconds to initiate another disk 
transfer on the same cylinder. It is used in determining the rotationally optimal 
layout for disk blocks within a file; the default value for Js_rotdelay is 2ms. 

Each file system has a statically allocated number of inodes. An inode is allocated 
for each NBPI bytes of disk space. The inode allocation strategy is extremely con¬ 
servative. 
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MAXIPG bounds the number of inodes per cylinder group, and is needed only to keep 
the structure simpler by having the only a single variable size element (the free bit 
map). 

N.B.: MAXIPG must be a multiple of INOPB(fs). 

MINBSIZE is the smallest allowable block size. With a MINBSIZE of 4096 it is pos¬ 
sible to create files of size 2'32 with only two levels of indirection. MINBSIZE must 
be big enough to hold a cylinder group block, thus changes to (struct eg) must keep 
its size within MINBSIZE. MAXCPG is limited only to dimension an array in (struct 
eg); it can be made larger as long as that structure’s size remains within the bounds 
dictated by MINBSIZE. Note that super blocks are never more than size SBSIZE. 

The path name on which the file system is mounted is maintained in fs_Jsmnt. 
MAXMNTLEN defines the amount of space allocated in the super block for this 
name. The limit on the amount of summary information per file system is defined by 
MAXCSBUFS. It is currently parameterized for a maximum of two million cylinders. 

Per cylinder group information is summarized in blocks allocated from the first 
cylinder group’s data blocks. These blocks are read in from fs^esaddr (size fs_cssize) 
in addition to the super block. 

N.B.: sizeof (struct esum) must be a power of two in order for the “fs_cs” macro to 
work. 


Super block for a file system : MAXBPC bounds the size of the rotational layout 
tables and is limited by the fact that the super block is of size SBSIZE. The size of 
these tables is inversely proportional to the block size of the file system. The size of 
the tables is increased when sector sizes are not powers of two, as this increases the 
number of cylinders included before the rotational pattern repeats ( /s_cpc). The 
size of the rotational layout tables is derived from the number of bytes remaining in 
(struct fs). 

MAXBPG bounds the number of blocks of data per cylinder group, and is limited by 
the fact that cylinder groups are at most one block. The size of the free block table 
is derived from the size of blocks and the number of remaining bytes in the cylinder 
group structure (struct eg). 

Inode: The inode is the focus of all file activity in the ICON/UX file system. There 
is a unique inode allocated for each active file, each current directory, each 
mounted-on file, text file, and the root. An inode is ‘named’ by its device/i-number 
pair. For further information, see the include file <sysf inode. /i>. 


SEE ALSO 

inode(4). 
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NAME 

fspec — format specification in text files 


DESCRIPTION 

It is sometimes convenient to maintain text files on the ICON/UXV system with non¬ 
standard tabs, (i.e., tabs which are not set at every eighth column). Such files must 
generally be converted to a standard format, frequently by replacing all tabs with 
the appropriate number of spaces, before they can be processed by ICON/UXV sys¬ 
tem commands. A format specification occurring in the first line of a text file 
specifies how tabs are to be expanded in the remainder of the file. 

A format specification consists of a sequence of parameters separated by blanks and 
surrounded by the brackets <: and :>. Each parameter consists of a keyletter, pos¬ 
sibly followed immediately by a value. The following parameters are recognized: 

t tabs The t parameter specifies the tab settings for the file. The value of tabs 
must be one of the following: 


1. a list of column numbers separated by commas, indicating tabs set 
at the specified columns; 

2. a — followed immediately by an integer n, indicating tabs at inter¬ 
vals of n columns; 

3. a — followed by the name of a “canned” tab specification. 

Standard tabs are specified by t— 8 , or equivalently, tl,9,17,25, etc. 
The canned tabs which are recognized are defined by the tabs{ 1) com¬ 
mand. 


s size The s parameter specifies a maximum line size. The value of size must 

be an integer. Size checking is performed after tabs have been 
expanded, but before the margin is prepended. 

m margin The m parameter specifies a number of spaces to be prepended to each 
line. The value of margin must be an integer. 

d The d parameter takes no value. Its presence indicates that the line 

containing the format specification is to be deleted from the converted 
file. 

e The e parameter takes no value. Its presence indicates that the current 

format is to prevail only until another format specification is encoun¬ 
tered in the file. 
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Default values, which are assumed for parameters not supplied, are t—8 and mO. If 
the s parameter is not specified, no size checking is performed. If the first line of a 
file does not contain a format specification, the above defaults are assumed for the 
entire file. The following is an example of a line containing a format specification: 

* <:t5,10,15 s72:> * 


If a format specification can be disguised as a comment, it is not necessary to code 
the d parameter. 

Several ICON/UXV system commands correctly interpret the format specification for a 
file. Among them is gath (see send{ 1C)) which may be used to convert files to a stan¬ 
dard format acceptable to other ICON/UXV system commands. 


SEE ALSO 

ed(l), newform(l), send(lC), tabs(l) in the ICON/UXV User Reference Manual. 
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NAME 

gettydefs — speed and terminal settings used by getty 


DESCRIPTION 

The /etc/gettydefs file contains information used by getty (IM) to set up the speed 
and terminal settings for a line. It supplies information on what the login prompt 
should look like. It also supplies the speed to try next if the user indicates the 
current speed is not correct by typing a <break> character. 

Each entry in /etc/gettydefs has the following format: 

label# initial-flags # final-flags # login-prompt #next-label 


Each entry is followed by a blank line. The various fields can contain quoted charac¬ 
ters of the form \b, \n, \c, etc., as well as \nnn, where nnn is the octal value of the 
desired character. The various fields are: 


label 


initial-flags 


final-flags 


login-prompt 


next-label 


This is the string against which getty tries to match its second argu¬ 
ment. It is often the speed, such as 1200, at which the terminal is 
supposed to run, but it need not be (see below). 

These flags are the initial ioctl{2) settings to which the terminal is to 
be set if a terminal type is not specified to getty . The flags that getty 
understands are the same as the ones listed in 
/usr/include/sys/termio.h (see termio( 7)). Normally only the 
speed flag is required in the initial-flags. Getty automatically sets the 
terminal to raw input mode and takes care of most of the other flags. 
The initial-flag settings remain in effect until getty executes login{\). 

These flags take the same values as the initial-flags and are set just 
prior to getty executes login. The speed flag is again required. The 
composite flag SANE takes care of most of the other flags that need 
to be set so that the processor and terminal are communicating in a 
rational fashion. The other two commonly specified final-flags are 
TAB3, so that tabs are sent to the terminal as spaces, and HUPCL, so 
that the line is hung up on the final close. 

This entire field is printed as the login-prompt. Unlike the above 
fields where white space is ignored (a space, tab or new-line), they are 
included in the login-prompt field. This field may include a %h to 
insert the host name into the login prompt, a %t to insert the tty 
device name into the login prompt, a %n to insert a newline, or a 
%% to insert the percent character into the login prompt. 

If this entry does not specify the desired speed, indicated by the user 
typing a <break> character, then getty will search for the entry with 
next-label as its label field and set up the terminal for those settings. 
Usually, a series of speeds are linked together in this fashion, into a 
closed set; For instance, 2400 linked to 1200, which in turn is linked 
to 300, which finally is linked to 2400. 


(C % 
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If getty is called without a second argument, then the first entry of /etc/gettydefs 
is used, thus making the first entry of /etc/gettydefs the default entry. It is also 
used if getty can not find the specified label. If /etc/gettydefs itself is missing, there 
is one entry built into the command which will bring up a terminal at 300 baud. 

It is strongly recommended that after making or modifying /etc/gettydefs, it be 
run through getty with the check option to be sure there are no errors. 


FILES 


/etc/gettydefs 


SEE ALSO 

ioctl(2). 

getty(lM), termio(7) in the ICON/UXV Administrator Reference Manual. 
login(l) in the ICON/UXV User Reference Manual. 
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NAME 

gps — graphical primitive string, format of graphical files 


DESCRIPTION 

GPS is a format used to store graphical data. Several routines have been developed 

to edit and display GPS files on various devices. Also, higher level graphics programs 

such as plot (in sfat(lG)) and vtoc (in <oc(lG)) produce GPS format output files. 

A GPS is composed of five types of graphical data or primitives. 

GPS PRIMITIVES 

lines The lines primitive has a variable number of points from which zero or 
more connected line segments are produced. The first point given pro¬ 
duces a move to that location. (A move is a relocation of the graphic cur¬ 
sor without drawing.) Successive points produce line segments from the 
previous point. Parameters are available to set color, weight, and style 
(see below). 

arc The arc primitive has a variable number of points to which a curve is fit. 

The first point produces a move to that point. If only two points are 
included, a line connecting the points will result; if three points a circular 
arc through the points is drawn; and if more than three, lines connect the 
points. (In the future, a spline will be fit to the points if they number 
greater than three.) Parameters are available to set color, weight, and 
style. 

text The text primitive draws characters. It requires a single point which 

locates the center of the first character to be drawn. Parameters are 
color, font, textsize, and textangle. 

hardware 

The hardware primitive draws hardware characters or gives control com¬ 
mands to a hardware device. A single point locates the beginning loca¬ 
tion of the hardware string. 

comment A comment is an integer string that is included in a GPS file but causes 
nothing to be displayed. All GPS files begin with a comment of zero 
length. 


GPS PARAMETERS 

color Color is an integer value set for arc, lines, and text primitives. 

weight Weight is an integer value set for arc and lines primitives to indicate line 
thickness. The value 0 is narrow weight, 1 is bold, and 2 is medium 
weight. 

style Style is an integer value set for lines and arc primitives to give one of the 
five different line styles that can be drawn on TEKTRONIX 4010 series 
storage tubes. They are: 

0 solid 
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1 dotted 

2 dot dashed 

3 dashed 

4 long dashed 


font An integer value set for text primitives to designate the text font to be 
used in drawing a character string. (Currently font is expressed as a 
four-bit weight value followed by a four-bit style value.) 

textsize Textsize is an integer value used in text primitives to express the size of 
the characters to be drawn. Textsize represents the height of characters 
in absolute universe-units and is stored at one-fifth this value in the size- 
orientation (so) word (see below). 


textangle Textangle is a signed integer value used in text primitives to express rota¬ 
tion of the character string around the beginning point. Textangle is 
expressed in degrees from the positive x-axis and can be a positive or 
negative value. It is stored in the size-orientation (so) word as a value 
256/360 of it’s absolute value. 


ORGANIZATION 

GPS primitives are organized internally as follows: 


lines 

arc 

text 

hardware 

comment 


cw points sw 

cw points sw 
cw point sw so [s<rim/] 


cw point 
cw [string 


string] 


cw Cw is the control word and begins all primitives. It consists of four bits 

that contain a primitive-type code and twelve bits that contain the 
word-count for that primitive. 


point(s) Points) is one or more pairs of integer coordinates. Text and hardware 
primitives only require a single point. Points) are values within a Carte¬ 
sian plane or universe having 64K (—32K to +32K) points on each axis. 

sw Sw is the style-word and is used in lines, arc, and text primitives. For all 

three, eight bits contain color information. In arc and lines eight bits are 
divided as four bits weight and four bits style. In the text primitive eight 
bits of sw contain the font. 


so So is the size-orientation word used in text primitives. Eight bits contain 

text size and eight bits contain text rotation. 

string String is a null-terminated character string. If the string does not end on 
a word boundary, an additional null is added to the GPS file to insure 
word-boundary alignment. 


SEE ALSO 

graphics(lG), stat(lG), toc(lG) in the ICON/UX\ r Administrator Reference Manual. 
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NAME 

group — group file 


DESCRIPTION 

Group contains for each group the following information: 


group name 
encrypted password 
numerical group ID 

comma-separated list of all users allowed in the group 


This is an ASCII file. The fields are separated by colons; each group is separated 
from the next by a new-line. If the password field is null, no password is demanded. 

This file resides in directory /etc. Because of the encrypted passwords, it can and 
does have general read permission and can be used, for example, to map numerical 
group ID’s to names. 


FILES 


/etc/group 


SEE ALSO 

crypt(3C), passwd(4). 

newgrp(l), passwd(l) in the lCON/UX\ r User Reference Manual. 
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NAME 

inittab — script for the init process 


DESCRIPTION 

The inittab file supplies the script to init’s role as a general process dispatcher. The 
process that constitutes the majority of init’s process dispatching activities is the 
line process /etc/getty that initiates individual terminal lines. Other processes typ¬ 
ically dispatched by init are daemons and the shell. 

The inittab file is composed of entries that are position dependent and have the fol¬ 
lowing format: 

id:rstate:action:process 


Each entry is delimited by a newline, however, a backslash (\) preceding a newline 
indicates a continuation of the entry. Up to 512 characters per entry are permitted. 
Comments may be inserted in the process field using the s/i(l) convention for com¬ 
ments. Comments for lines that spawn gettys are displayed by the u>/io(l) command. 
It is expected that they will contain some information about the line such as the 
location. There are no limits (other than maximum entry size) imposed on the 
number of entries within the inittab file. The entry fields are: 

id This is one or two characters used to uniquely identify an entry. 

rstate This defines the run-level in which this entry is to be processed. Run-levels 
effectively correspond to a configuration of processes in the system. That 
is, each process spawned by init is assigned a run-level or run-levels in which 
it is allowed to exist. The run-levels are represented by a number ranging 
from 0 through 6. As an example, if the system is in run-level 1, only those 
entries having a 1 in the rstate field will be processed. When init is 
requested to change run-levels, all processes which do not have an entry in 
the rstate field for the target run-level will be sent the warning signal 
(SIGTERM) and allowed a 20-second grace period before being forcibly ter¬ 
minated by a kill signal (SIGKILL). The rstate field can define multiple 
run-levels for a process by selecting more than one run-level in any combi¬ 
nation from 0—6. If no run-level is specified, then the process is assumed to 
be valid at all run-levels 0—6. There are three other values, a, b and c, 
which can appear in the rstate field, even though they are not true run- 
levels. Entries which have these characters in the rstate field are processed 
only when the telinit (see mt7(lM)) process requests them to be run (regard¬ 
less of the current run-level of the system). They differ from run-levels in 
that init can never enter run-level a, b or c. Also, a request for the execu¬ 
tion of any of these processes does not change the current run-level. Furth¬ 
ermore, a process started by an a, b or c command is not killed when init 
changes levels. They are only killed if their line in /etc/inittab is marked 
off in the action field, their line is deleted entirely from /etc/inittab, or 
init goes into the SINGLE USER state. 
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action Key words in this field tell init how to treat the process specified in the pro¬ 
cess field. The actions recognized by init are as follows: 


respawn 


wait 


once 


boot 


bootwait 


powerfail 

powerwait 


off 


ondemand 


If the process does not exist then start the process, do not 
wait for its termination (continue scanning the inittab file), 
and when it dies restart the process. If the process currently 
exists then do nothing and continue scanning the inittab file. 

Upon init’s entering the run-level that matches the entry’s 
rstate, start the process and wait for its termination. All 
subsequent reads of the inittab file while init is in the same 
run-level will cause init to ignore this entry. 

Upon init’s entering a run-level that matches the entry’s 
rstate, start the process, do not wait for its termination. 
When it dies, do not restart the process. If upon entering a 
new run-level, where the process is still running from a previ¬ 
ous run-level change, the program will not be restarted. 

The entry is to be processed only at inif’s boot-time read of 
the inittab file. Init is to start the process, not wait for its ter¬ 
mination; and when it dies, not restart the process. In order 
for this instruction to be meaningful, the rstate should be the 
default or it must match init’s run-level at boot time. This 
action is useful for an initialization function following a 
hardware reboot of the system. 

The entry is to be processed only at init’s boot-time read of 
the inittab file. Init is to start the process, wait for its termi¬ 
nation and, when it dies, not restart the process. 

Execute the process associated with this entry only when init 
receives a power fail signal (SIGPWR see signal( 2)). 

Execute the process associated with this entry only when init 
receives a power fail signal (SIGPWR) and wait until it ter¬ 
minates before continuing any processing of inittab. 

If the process associated with this entry is currently running, 
send the warning signal (SIGTERM) and wait 20 seconds 
before forcibly terminating the process via the kill signal 
(SIGKILL). If the process is nonexistent, ignore the entry. 

This instruction is really a synonym for the respawn action. 
It is functionally identical to respawn but is given a different 
keyword in order to divorce its association with run-levels. 
This is used only with the a, b or c values described in the 
rstate field. 


initdefault An entry with this action is only scanned when init initially 
invoked. Init uses this entry, if it exists, to determine which 
run-level to enter initially. It does this by taking the highest 
run-level specified in the rstate field and using that as its ini¬ 
tial state. If the rstate field is empty, this is interpreted as 
0123456 and so init will enter run-level 6. Also, the initde¬ 
fault entry cannot specify that init start in the SINGLE USER 
state. Additionally, if init does not find an initdefault entry 
in /etc/inittab, then it will request an initial run-level from 
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the user at reboot time. 

sysinit Entries of this type are executed before init tries to access the 
console. It is expected that this entry will be only used to ini¬ 
tialize devices on which init might try to ask the run-level 
question. These entries are executed and waited for before 
continuing. 

process This is a sh command to be executed. The entire process field is prefixed 
with exec and passed to a forked sh as sh —c 'exec command '. For this 
reason, any legal sh syntax can appear in the process field. Comments can 
be inserted with the ; # comment syntax. 


FILES 


/etc/inittab 


SEE ALSO 

exec(2), open(2), signal(2). 

getty(lM), init(lM) in the ICON/UXV Administrator Reference Manual. 
sh(l), who(l) in the ICON/UXV User Reference Manual. 
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NAME 

inode — format of an i-node 


SYNOPSIS 

^include <sys/types.h> 
^include <sys/inode.h> 


DESCRIPTION 

An i-node for a plain file or directory in a file system has the following structure 
defined by <sys/inode.h>. 

/* Common inode structure for disk and memory inodes. */ 


^define 

NDADDR 12 

/* direct addresses in inode */ 

#define 

NIADDR 3 

/* indirect addresses in inode */ 

struct 

{ 

u_short 

icommon 


ic_mode; 

/* 0: mode and type of file */ 

short 

ic_nlink; 

/* 2: number of links to file */ 

uid_t 

ic_uid; 

/* 4: owner’s user id */ 

gid—t 

ic_gid; 

/* 6: owner’s group id */ 

quad 

ic_size; 

/* 8: number of bytes in file */ 

time_t 

ic_atime; 

/* 16: time last accessed */ 

long 

ic_atspare; 

time_t 

ic_mtime; 

/* 24: time last modified */ 

long 

ic_mtspare; 

/* 32: last time inode changed */ 

time_t 

ic_ctime; 

long 
union { 

ic_ctspare; 


daddr_t 

La [NDADDR]; 

}di_udb; 

short 

i_f[NSADDR]; 

daddr_t 

ic_ib [NIADDR]; 

/* 88: indirect blocks */ 

long 

ic_flags; 

/* 100: status, currently unused */ 

long 

ic_blocks; 

/* 104: blocks actually held */ 

ujong 

ic_loadmap[5]; 

/* 108: past loading history */ 


}; 


/* Inode structure as it appears on a disk block. */ 

struct dinode { 
union { 

struct icommon di_icom; 
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} di_un; 


char 


di_size [128]; 


For the meaning of the defined type timejt see types(5). 


FILES 


/ usr /include/sys /inode .h 


SEE ALSO 

stat(2), fs(4), types(5). 
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NAME 

issue — issue identification file 

DESCRIPTION 

The file /etc/usue contains the issue or project identification to be printed as a 
login prompt. This is an ASCII file which is read by program getty and then written 
to any terminal spawned or respawned from the lines file. 

FILES 

/etc/issue 
SEE ALSO 

login(l) in the ICON/UXV User Reference Manual. 
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NAME 

ldfcn — common object file access routines 


SYNOPSIS 

^include <stdio.h> 
#include <filehdr.h> 
^include <ldfcn.h> 


DESCRIPTION 

The common object file access routines are a collection of functions for reading an 
object file that is in common object file form. Although the calling program must 
know the detailed structure of the parts of the object file that it processes, the rou¬ 
tines effectively insulate the calling program from knowledge of the overall structure 
of the object file. 

The interface between the calling program and the object file access routines is 
based on the defined type LDFILE, defined as struct ldfile, declared in the header 
file ldfcn.h. The primary purpose of this structure is to provide uniform access to 
both simple object files and to object files that are members of an archive file. 

The function ldopen( 3X) allocates and initializes the LDFILE structure and returns a 
pointer to the structure to the calling program. The fields of the LDFILE structure 
may be accessed individually through macros defined in ldfcn.h and contain the fol¬ 
lowing information: 

LDFILE *ldptr; 

TYPE(ldptr) The file magic number used to distinguish between archive members 
and simple object files. 

IOPTR(ldptr) The file pointer returned by fopen and used by the standard 
input/output functions. 

OFFSET(ldptr) The file address of the beginning of the object file; the offset is non¬ 
zero if the object file is a member of an archive file. 

HEADER(ldptr) The file header structure of the object file. 

The object file access functions themselves may be divided into four categories: 


(1) functions that open or close an object file 

ldopen( 3X) and ldopen( 3X) 

open a common object file 
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.\ 

ldclose( 3X) and ldclose( 3X) v —' 

close a common object file 

(2) functions that Tead headeT or symbol table information 
ldahreud( 3X) 

read the archive header of a member of an archive file 
ldfhread{ 3X) 

read the file header of a common object file 
ld$hread( 3X) and ldskread( 3X) 

read a section header of a common object file 
ldtbread(3X) 

read a symbol table entry of a common object file 
ldgetname(3X) 

retrieve a symbol name from a symbol table entry or from the 
string table 


(3) functions that position an object file at (seek to) the start of the section, 
relocation, or line number information for a particular section. 

ldohseek( 3X) 

seek to the optional file header of a common object file 
ldsseek(SX) and ldsseek(3X) 

seek to a section of a common object file 
ldr$eek(3X) and ldrseek(3X) 

seek to the relocation information for a section of a common 
object file 

ldlseek(3X) and ldlseek( 3X) 

seek to the line number information for a section of a common 4 

object file V , 


2 


Icon International, Inc. 



LDFCN (4) 


FILE FORMATS 


LDFCN (4) 


ldtbseek(ZX) 

seek to the symbol table of a common object file 


(4) the function Idtbindex(3X) which returns the index of a particular common 
object file symbol table entry. 


These functions are described in detail on their respective manual pages. 

All the functions except ldopen( 3X), ldgetname(3X), Idopen(SX), and ldtbindex(3X) 
return either SUCCESS or FAILURE, both constants defined in ldfcn.h. 
Ldopen( 3X) and ldopen( 3X) both return pointers to an LDFILE structure. 

Additional access to an object file is provided through a set of macros defined in 
ldfcn.h. These macros parallel the standard input/output file reading and manipu¬ 
lating functions, translating a reference of the LDFILE structure into a reference to 
its file descriptor field. 

The following macros are provided: 

GETC(ldptr) 

FGETC(ldptr) 

GETW(ldptr) 

UNGETC(c, Idptr) 

FGETS(s, n, Idptr) 

FREAD((char *) ptr, sizeof (*ptr), nitems, Idptr) 

FSEEK(ldptr, offset, ptrname) 

FTELL(ldptr) 

REWIND(ldptr) 

FEOF(ldptr) 

FERROR(ldptr) 

FILENO(ldptr) 

SETBUF(ldptr, buf) 

STROFFSET(ldptr) 


The STROFFSET macro calculates the address of the stTing table in a UNIX system 
release 5.0 object file. See the manual entries for the corresponding standard 
input/output library functions for details on the use of the rest of the macros. 

The program must be loaded with the object file access routine library libld.a. 
WARNING 

The macro FSEEK defined in the header file ldfcn.h translates into a call to the 
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standard input/output function fseek( 3S). FSEEK should not be used to seek from 
the end of an archive file since the end of an archive file may not be the same as the 
end of one of its object file members! 


SEE ALSO 

fseek(3S), ldahread(3X), ldclose(3X), ldgetname(3X), ldfhread(3X), ldlread(3X), 
ldlseek(3X), ldohseek(3X), ldopen(3X), ldrseek(3X), ldlseek(3X), ldshread(3X), 
ldtbindex(3X), ldtbread(3X), ldtbseek(3X), intro(5). 
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NAME 

linenum — line number entries in a common object file 


SYNOPSIS 

#include <linenum.h> 


DESCRIPTION 

Compilers based on pcc generate an entry in the object file for each C source line on 
which a breakpoint is possible (when invoked with the —g option; see cc(l)). Users 
can then reference line numbers when using the appropriate software test system 
(see sdb( 1)). The structure of these line number entries appears below. 

struct lineno 

{ 

union 

{ 

long Lsymndx ; 

long Lpaddr ; 

} l_addr ; 

unsigned short Llnno ; 

}; 


Numbering starts with one for each function. The initial line number entry for a 
function has Llnno equal to zero, and the symbol table index of the function’s entry 
is in Lsymndx. Otherwise, Llnno is non-zero, and Lpaddr is the physical address of 
the code for the referenced line. Thus the overall structure is the following: 


Laddr 

Unno 

function symtab index 

0 

physical address 

line 

physical address 

line 

function symtab index 

0 

physical address 

line 

physical address 

line 
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SEE ALSO 

a.out(4). 

cc(l), sdb(l) in the ICON/UXV User Reference Manual. 


2 


Icon International, Inc. 



MNTTAB( 4 ) 


FILE FORMATS 


MNTTAB(4) 


NAME 

mnttab — mounted file system table 


SYNOPSIS 

#include <mnttab.h> 


DESCRIPTION 

Mnttab resides in directory /etc and contains a table of devices, mounted by the 
moun<(lM) command, in the following structure as defined by <mnttab.h>: 

struct mnttab { 

char mt_dev[32]; 

char mt_filsys[32]; 

short mt_ro_flg; 

time_t mt_time; 


Each entry is 70 bytes in length; the first 32 bytes are the null-padded name of the 
place where the special file is mounted; the next 32 bytes represent the null-padded 
root name of the mounted special file; the remaining 6 bytes contain the mounted 
special file’s read/write permissions and the date on which it was mounted. 

The maximum number of entries in mnttab is based on the system parameter 
NMOUNT located in /usr/src/uts/cf/conf.c, which defines the number of allowable 
mounted special files. 


SEE ALSO 

mount(lM), setmnt(lM) in the ICON/UXV Administrator Reference Manual. 
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NAME 

mttys — Multi-Link partition information 

DESCRIPTION 

The file fetc/mttys is read by the dose program and specifies the maximum number 
of Multi-Link partitions that can be active. There is cuTTently only one line in the 
file, which contains the decimal number of partitions. Currently the number may 
range from 1 to 8. 

FILES 

/etc/mttys 

SEE ALSO 

dosc(l) 
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NAME 

passwd — password file 


DESCRIPTION 

Passwd contains for each user the following information: 


login name 
encrypted password 
numerical user ID 
numerical group ID 

GCOS job number, box number, optional GCOS user ID 
initial working directory 
program to use as shell 


This is an ASCII file. Each field within each user’s entry is separated from the next 
by a colon. The GCOS field is used only when communicating with that system, and 
in other installations can contain any desired information. Each user is separated 
from the next by a new-line. If the password field is null, no password is demanded; 
if the shell field is null, the shell itself is used. 

This file resides in directory /etc. Because of the encrypted passwords, it can and 
does have general read permission and can be used, for example, to map numerical 
user IDs to names. 

The encrypted password consists of 13 characters chosen from a 64-character alpha¬ 
bet (., /, 0—9, A—Z, a—z), except when the password is null, in which case the 
encrypted password is also null. Password aging is effected for a particular user if his 
encrypted password in the password file is followed by a comma and a non-null 
string of characters from the above alphabet. (Such a string must be introduced in 
the first instance by the super-user.) 

The first character of the age, M say, denotes the maximum number of weeks for 
which a password is valid. A user who attempts to login after his password has 
expired will be forced to supply a new one. The next character, m say, denotes the 
minimum period in weeks which must expire before the password may be changed. 
The remaining characters define the week (counted from the beginning of 1970) when 
the password was last changed. (A null string is equivalent to zero.) M and m have 
numerical values in the range 0—63 that correspond to the 64-character alphabet 
shown above (i.e., / = 1 week; z — 63 weeks). If m = M — 0 (derived from the string 
. or ..) the user will be forced to change his password the next time he logs in (and 
the “age” will disappear from his entry in the password file). If m > M (signified, 
e.g., by the string ./) only the super-user will be able to change the password. 
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FILES 


/etc/passwd 


SEE ALSO 

a64l(3C), crypt(3C), getpwent(3C), group(4). 

login(l), passwd(l) in the ICON/UXV User Reference Manual. 
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NAME 

plot — graphics interface 


DESCRIPTION 


Files of this format are produced by routines described in plol(3X) and are inter¬ 
preted for various devices by commands described in tp/ot(lG). A graphics file is a 
stream of plotting instructions. Each instruction consists of an ASCII letter usually 
followed by bytes of binary information. The instructions are executed in order. A 
point is designated by four bytes representing the x and y values; each value is a 
signed integer. The last designated point in an 1, m, n, or p instruction becomes the 
“current point” for the next instruction. 


Each of the following descriptions begins with the name of the corresponding routine 

in plot{ 3X). 

m move: The next four bytes give a new current point. 

n cont: Draw a line from the current point to the point given by the next four 
bytes. See tplot(lG). 

p point: Plot the point given by the next four bytes. 

1 line: Draw a line from the point given by the next four bytes to the point given 
by the following four bytes. 

t label: Place the following ASCII string so that its first character falls on the 
current point. The string is terminated by a new-line. 

e erase: Start another frame of output. 

f linemod: Take the following string, up to a new-line, as the style for drawing 
further lines. The styles are “dotted”, “solid”, “longdashed”, “shortdashed”, and 
“dotdashed”. Effective only for the — T4014 and —Tver options of tplot( 1G) 
(TEKTRONIX 4014 terminal and Versatec plotter). 

s space: The next four bytes give the lower left corner of the plotting area; the fol¬ 
lowing four give the upper right corner. The plot will be magnified or reduced to 
fit the device as closely as possible. 


Space settings that exactly fill the plotting area with unity scaling appear below for 
devices supported by the filters of tplot( 1G). The upper limit is just outside the plot¬ 
ting area. In every case the plotting area is taken to be square; points outside may 
be displayable on devices whose face is not square. 


DASI 300 
DASI 300s 
DASI 450 

TEKTRONIX 4014 
Versatec plotter 


space(0, 0, 4096, 4096); 
space(0, 0, 4096, 4096); 
space(0, 0, 4096, 4096); 
space(0, 0, 3120, 3120); 
space(0, 0, 2048, 2048); 
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SEE ALSO 

plot(3X), gps(4), term(5). 

graph(lG), tplot(lG) in the ICON/UXV User Reference Manual. 


WARNING 

The plotting library plot{ 3X) and the curses library curses(3X) both use the names 
erase() and move(). The curses versions are macros. If you need both libraries, put 
the plot(3X) code in a different source file than the curses(3X) code, and/or #undef 
moveQ and eraseQ in the plot( 3X) code. #! /bin/csh foreach i ( *.4 ) tbl $i j eqn J iroff 
-manvcat cat a.out.4 acct.4 ar.4 checklist.4 core.4 cpio.4 dir.4 > tmpfile tbl tmpfile J 
eqn | iroff -manvcat cat dosdisks.4 dosprinters.4 dstrules.4 filehdr.4 fs.4 fspec.4 > 
tmpfile tbl tmpfile j eqn j iroff -manvcat cat gettydefs.4 gps.4 group.4 inittab.4 
inode.4 intro.4 issue.4 ldfcn.4 > tmpfile tbl tmpfile ] eqn J iroff -manvcat cat line- 
num.4 mnttab.4 mttys.4 passwd.4 plot.4 printall profile.4 > tmpfile tbl tmpfile J eqn j 
iroff -manvcat cat reloc.4 sccsfile.4 scnhdr.4 smiledisks.4 syms.4 term.4 termcap.4 ter- 
minfo.4 utmp.4 uxrc.4 > tmpfile tbl tmpfile J eqn j iroff -manvcat end 
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NAME 

profile — setting up an environment at login time 


DESCRIPTION 

If your login directory contains a file named .profile, that file will be executed (via 
exec .profile) before your session begins; .profiles are handy for setting exported 
environment variables and terminal modes. If the file /etc/profile exists, it will be 
executed for every user before the .profile. The following example is typical (except 
for the comments): 

# Make some environment variables global 
export MAIL PATH TERM 

# Set file creation mask 
umask 22 

# Tell me when new mail comes in 
MAIL=/usr/mail/my name 

# Add my /bin directory to the shell search sequence 
PATH=$PATH:$HOME/bin 

# Set terminal type 
echo "terminal: \c” 
read TERM 

case $TERM in 


300) 

stty 

cr2 

nlO 

tabs; tabs;; 

300s) 

stty 

cr2 

nlO 

tabs; tabs;; 

450) 

stty 

cr2 

nlO 

tabs; tabs;; 

hp) 

stty 

crO 

nlO 

tabs; tabs;; 

745 J735) 

stty 

crl 

nil 

—tabs; TERM=745;; 

43) 

stty 

crl 

nlO 

—tabs;; 

4014 |tek) 

stty 

crO 

nlO 

-tabs ffl; TERM=4014; echo "\33;";; 


*) echo "$TERM unknown”;; 

esac 


FILES 

IHOME/.profile 

/etc/profile 


SEE ALSO 

environ(5), term(5). 

env(l), login(l), mail(l), sh(l), stty(l), su(l) in the ICON/UX\ r User Reference Manual. 
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NAME 

reloc — relocation information for a common object file 


SYNOPSIS 

^include <reloc.h> 


DESCRIPTION 

Object files have one relocation entry for each relocatable reference in the text or 
data. If relocation information is present, it will be in the following format. 


struct 

{ 

reloc 

long 

r_vaddr; 

/* (virtual) address of reference ♦/ 


long 

r_symndx ; 

/♦ index into symbol table */ 

}; 

short 

r_type ; 

/* relocation type */ 

/* 

* All 

generics 




* reloc. already performed to symbol in the same section 
*/ 

^define R_ABS 0 

/* 

* 3B computer generic 

* 24-bit direct reference 

* 24-bit “relative” reference 

* 16-bit optimized “indirect” TV reference 

* 24-bit “indirect” TV reference 

* 32-bit “indirect” TV reference 

*/ 

#define RJDIR24 04 
#define R_REL24 05 
#define R_OPTl6 014 
#define RJND24 015 
#define RJND32 016 


* DEC Processors VAX 11/780 and VAX 11/750 


* 

*/ 

#define R_RELBYTE 017 

#define RJRELWORD 020 

#define R_RELLONG 021 

#define R_PCRBYTE 022 
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#define R_PCRWORD 023 

#define R_PCRLONG 024 


As the link editor reads each input section and performs relocation, the relocation 
entries are read. They direct how references found within the input section are 
treated. 


R_ABS 

R_DIR24 

R_REL24 


R_OPTl6 


The reference is absolute, and no relocation is necessary. The entry 
will be ignored. 

A direct, 24-bit reference to a symbol’s virtual address. 

A “PC-relative”, 24-bit reference to a symbol’s virtual address. Rela¬ 
tive references occur in instructions such as jumps and calls. The 
actual address used is obtained by adding a constant to the value of 
the program counter at the time the instruction is executed. 

An optimized, indirect, 16-bit reference through a transfer vector. The 
instruction contains the offset into the transfer vector table to the 
transfer vector where the actual address of the referenced word is 
stored. 


R_IND24 An indirect, 24-bit reference through a transfer vector. The instruction 
contains the virtual address of the transfer vector, where the actual 
address of the referenced word is stored. 


R_IND32 An indirect, 32-bit reference through a transfer vector. The instruction 
contains the virtual address of the transfer vector, where the actual 
address of the referenced word is stored. 


R_RELBYTE A direct 8-bit reference to a symbol’s virtual address. 
R_RELWORD 

A direct 16-bit reference to a symbol’s virtual address. 
RJRELLONG A direct 32-bit reference to a symbol’s virtual address. 
R_PCRBYTE A “PC-relative”, 8-bit reference to a symbol’s virtual address. 


RJPCRWORD 

A “PC-relative”, 16-bit reference to a symbol’s virtual address. 


R_PCRLONG 

A “PC-relative”, 32-bit reference to a symbol’s virtual address. 


On the VAX processors relocation of a symbol index of -1 indicates that the relative 
difference between the current segment’s start address and the program’s load 
address is added to the relocatable address. 


Other relocation types will be defined as they are needed. 

Relocation entries are generated automatically by the assembler and automatically 
utilized by the link editor. A link editor option exists for removing the relocation 
entries from an object file. 
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SEE ALSO 

a.out(4), syms(4). 

ld(l), strip(l) in the ICON/UXV User Reference Manual. 
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NAME 

sccsfile — format of SCCS file 


DESCRIPTION 

An file is an ASCII file. It consists of six logical parts: the checksum, the delta table 
(contains information about each delta), user names (contains login names and/or 
numerical group IDs of users who may add deltas), flags (contains definitions of inter¬ 
nal keywords), comments (contains arbitrary descriptive information about the file), 
and the body (contains the actual text lines intermixed with control lines). 

Throughout an file there are lines which begin with the ASCII SOH (start of head¬ 
ing) character (octal 001). This character is hereafter referred to as the control char¬ 
acter and will be represented graphically as Any line described below which is 
not depicted as beginning with the control character is prevented from beginning 
with the control character. 

Entries of the form 

represent a five-digit string (a number between 00000 and 99999). 

Each logical part of an file is described in detail below. 

Checksum 

The checksum is the first line of an file. The form of the line is: 

@h 

The value of the checksum is the sum of all characters, except those of the 
first line. The @h provides a magic number of (octal) 064001. 

Delta table 

The delta table consists of a variable number of entries of the form: 

@5 // 

@d <type> <SCCS ID> yr/mo/da hr:mi:se <pgmr> 

@i ... 

@x ... 

@g ... 

@m < number> 


@c <comments> ... 


@e 

The first line {@a) contains the number of lines inserted/deleted/unchanged, 
respectively. The second line (@d) contains the type of the delta (currently, 
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normal: D, and removed: R), the ED of the delta, the date and time of crea¬ 
tion of the delta, the login name corresponding to the real user ID at the time 
the delta was created, and the serial numbers of the delta and its predeces¬ 
sor, respectively. 

The @i, @x, and @g lines contain the serial numbers of deltas included, 
excluded, and ignored, respectively. These lines are optional. 

The @m lines (optional) each contain one number associated with the delta; 
the @e lines contain comments associated with the delta. 

The @e line ends the delta table entry. 

User names 

The list of login names and/or numerical group IDs of users who may add del¬ 
tas to the file, separated by new-lines. The lines containing these login names 
and/or numerical group IDs are surrounded by the bracketing lines @u and 
@U. An empty list allows anyone to make a delta. Any line starting with a 
! prohibits the succeeding group or user from making deltas. 

Flags 

Keywords used internally (see admin( 1) for more information on their use). 
Each flag line takes the form: 

@f <flag> <optional text> 

The following flags are defined: 

@f t <type of program> 

@f v <program name> 

@f i <keyword string> 

@fb 

@f m <module name> 

@f f <floor> 

@f c <ceiling> 

@f d <default-sid> 

@f n 
@fj 

@f 1 <lock-releases> 

@f q <user defined> 

@f z <reserved for use in interfaces> 

The t flag defines the replacement for the %Y% identification keyword. The 
v flag controls prompting for numbers in addition to comments; if the 
optional text is present it defines an number validity checking program. The 
i flag controls the warning/error aspect of the “No id keywords” message. 
When the i flag is not present, this message is only a warning; when the i flag 
is present, this message will cause a “fatal” error (the file will not be gotten, 
or the delta will not be made). When the b flag is present the — b keyletter 
may be used on the get command to cause a branch in the delta tree. The m 
flag defines the first choice for the replacement text of the %M% 
identification keyword. The f flag defines the “floor” release; the release 
below which no deltas may be added. The c flag defines the “ceiling” release; 
the release above which no deltas may be added. The d flag defines the 
default to be used when none is specified on a get command. The n flag 
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causes delta to insert a “null” delta (a delta that applies no changes) in those 
releases that are skipped when a delta is made in a new release (e.g., when 
delta 5.1 is made after delta 2.7, releases 3 and 4 are skipped). The absence 
of the n flag causes skipped releases to be completely empty. The j flag 
causes get to allow concurrent edits of the same base . The 1 flag defines a 
list of releases that are locked against editing (get(l) with the —e keyletter). 
The q flag defines the replacement for the %Q% identification keyword. The 
x flag is used in certain specialized interface programs. 

Comments 

Arbitrary text is surrounded by the bracketing lines @t and @T. The com¬ 
ments section typically will contain a description of the file’s purpose. 

Body 

The body consists of text lines and control lines. Text lines do not begin with 
the control character, control lines do. There are three kinds of control lines: 
insert,'delete, and end, represented by: 

@1 

@D 

@E 

respectively. The digit string is the serial number corresponding to the delta 
for the control line. 


SEE ALSO 

admin(l), delta(l), get(l), prs(l) in the ICON/UXV User Reference Manual. 
Source Code Control System User Guide in the ICON/UXV User Guide. 
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NAME 

scnhdr — section header for a common object file 


SYNOPSIS 

^include <acnhdr.h> 


DESCRIPTION 

Every common object file has a table of section headers to specify the layout of the 
data within the file. Each section within an object file has its own header. The C 
structure appears below. 


struct scnhdr 
{ 

char 

long 

long 

long 

long 

long 

long 

unsigned short 
unsigned short 
long 

}; 


s_name[SYMNMLEN]; /* section name */ 
s_paddr; /* physical address */ 

s_vaddr; /* virtual address */ 

s_jsize; /* section size */ 

s_scnptr; /* file ptr to raw data */ 
s_relptr; /* file ptr to relocation */ 
sjnnoptr; /* file ptr to line numbers */ 
s_nreloc; /* # reloc entries */ 

s_nlnno; /* # line number entries */ 

s_flags; /* flags */ 


File pointers are byte offsets into the file; they can be used as the offset in a call to 
fseek(ZS). If a section is initialized, the file contains the actual bytes. An uninitial¬ 
ized section is somewhat different. It has a size, symbols defined in it, and symbols 
that refer to it. But it can have no relocation entries, line numbers, or data. Conse¬ 
quently, an uninitialized section has no raw data in the object file, and the values for 
s_scnptr, s__relptr, $_lnnoptr , s^nreloc, and s_nlnno are zero. 


SEE ALSO 

fseek(3S), a.out(4). 

ld(l) in the ICON/UXV User Reference Manual. 
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NAME 

smiledisks — list of SMILE virtual disks 


DESCRIPTION 

The file /etc/smiledisks contains a list of the pathnames for all files to be used as 
vdisks for computers connected to SMILE. The files are created by smiledisk(8) and 
each new vdisk pathname is appended to / etc/smiledisks by smiledisk. Each vdisk is 
specified by a line in /etc/smiledisks. There are three fields. The first field is the 
label that is used to refer to the specified vdisk in the local configuration file. The 
second field is the pathname for the vdisk. The third field is the description. To 
delete a vdisk, remove the ICON/UX file, then edit / etc/smiledisks and remove the 
line specifying the deleted vdisk. Removing a ‘d’ partition vdisk is somewhat more 
involved; contact Icon for further assistance. 

The local configuration files contain the mapping for vdisks for the computer 
attached to each port on the SMILE host board. The number at the end of the 
filename refers to the port that is being configured. The local configuration file for 
port 0 would be / etc/smiledisks_00. Each disk is identified by a line in the local 
configuration file. The line contains the label assigned in /etc/smiledisks and then 
the read/write status. The read/write status is defined by RW for read/write and 
RO for read only. The vdisks are accessed in the order in which they appear in the 
configuration file. Only one computer can have a vdisk open read/write at a time. 
The request for read/write will be rejected if the vdisk is already read/write for 
someone else. 


EXAMPLE 

/etc/smiledisks contains the following information and the vdisk labeled c is to be 
opened read/write on port 2. 

c:/usr/smiledisk:this is the comment for label c 
d:/usr/SMILEb:this is the comment for label d 
cat:/usr/testdisk:this is description 

/ etc/smiledisks^OS would then contain the following. 

c:rw 


FILES 


/etc /smileprinters 
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SEE ALSO 

smiledisk(8), Technical Note on SMILE 
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NAME 

syms — common object file symbol table format 


SYNOPSIS 

^include <syms.h> 


DESCRIPTION 

Common object files contain information to support symbolic software testing (see 
sd6(l)). Line number entries, linenum{ 4), and extensive symbolic information permit 
testing at the C source level. Every object file’s symbol table is organized as shown 
below. 

File name 1. 

Function 1. 

Local symbols for function 1. 

Function 2. 

Local symbols for function 2. 

Static externs for file 1. 

File name 2. 

Function 1. 

Local symbols for function 1. 

Function 2. 

Local symbols for function 2. 

Static externs for file 2. 


Defined global symbols. 
Undefined global symbols. 


The entry for a symbol is a fixed-length structure. The members of the structure 
hold the name (null padded), its value, and other information. The C structure is 
given below. 

#define SYMNMLEN 8 
#define FILNMLEN 14 
struct svment 

union /* all ways to get symbol name */ 

char _nj am e [SYMNMLEN]; /* symbol name */ 

struct 
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r 

r 


long 

_n_zeroes; 

/* == OL when in string table : 

long 

} -n-n; 

_n_offset; 

/* location of name in table */ 

char 

I n- 

*_n_nptr[2]; 

/* allows overlaying */ 

long 

n_value; 

/* value of symbol */ 

short 

n_scnum; 

/* section number */ 

unsigned short 

n_type; 

/* type and derived type */ 

char 

n_sclass; 

/* storage class */ 

char 

}; 

n_numaux; 

/* number of aux entries */ 

#define n_name 

_n._n_name 


#define n_zeroes 

_n ._n_n ,_n_zeroes 

#define n_offset 

_n ._n_n ._n_offse t 

#define n_nptr 

_n._n_nptr[l] 



Meaningful values and explanations for them are given in both syms.h and Common 
Object File Format. Anyone who needs to interpret the entries should seek more 
information in these sources. Some symbols require more information than a single 
entry; they are followed by auxiliary entries that are the same size as a symbol 
entry. The format follows. 


union auxent 

{ 

struct 

{ 

long 

union 


x_tagndx; 


/- 

! v... 
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{ 

struct 


} 

struct 

{ 

} 

struct 

{ 


{ 

unsigned short x_lnno; 
unsigned short x_size; 

} x_lnsz; 
long x_fsize; 

} x_misc; 
union 
{ 

struct 


{ 

long xjnnoptr; 

long x_endndx; 

} x_fcn; 

struct 

{ 

unsigned short x_dimen[DIMNUM]; 
} x_ary; 

} x_fcnary; 

unsigned short x_tvndx; 
x_sym; 


char x_fname[FILNMLEN]; 
x_file; 


long x_scnlen; 
unsigned short x_nreloc; 
unsigned short x_nlinno; 
} x_scn; 


struct 

{ 

long x_tvfill; 

unsigned short x_tvlen; 
unsigned short x_tvran[2]; 
} X—tv; 

}; 


Indexes of symbol table entries begin at zero. 


SEE ALSO 

a.out(4), linenum(4). 

sdb(l) in the ICON/UXV User Reference Manual. 
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CAVEATS 

On machines in which longs are equivalent to ints (3B 20 computer, VAX), they are 
converted to ints in the compiler to minimize the complexity of the compiler code 
generator. Thus the information about which symbols are declared as longs and 
which, as ints, does not show up in the symbol table. 
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NAME 

term — format of compiled term file. 


SYNOPSIS 

term 


DESCRIPTION 

Compiled terminfo descriptions are placed under the directory /usr/lib/terminfo. 
In order to avoid a linear search of a huge 1C0N/UXV system directory, a two-level 
scheme is used: /usr/Iib/terminfo/c/name where name is the name of the termi¬ 
nal, and c is the first character of name. Thus, actj can be found in the file 
/usr/lib/terminfo/a/act4. Synonyms for the same terminal are implemented by 
multiple links to the same compiled file. 

The format has been chosen so that it will be the same on all hardware. An 8 or 
more bit byte is assumed, but no assumptions about byte ordering or sign extension 
are made. 

The compiled file is created with the compile program, and read by the routine 
setupterm. Both of these pieces of software are part of curses( 3X). The file is 
divided into six parts: the header, terminal names, boolean flags, numbers, strings, 
and string table. 

The header section begins the file. This section contains six short integers in the for¬ 
mat described below. These integers are (1) the magic number (octal 0432); (2) the 
size, in bytes, of the names section; (3) the number of bytes in the boolean section; 
(4) the number of short integers in the numbers section; (5) the number of offsets 
(short integers) in the strings section; (6) the size, in bytes, of the string table. 

Short integers are stored in two 8-bit bytes. The first byte contains the least 
significant 8 bits of the value, and the second byte contains the most significant 8 
bits. (Thus, the value represented is 256*second+first.) The value —1 is represented 
by 0377, 0377, other negative value are illegal. The —1 generally means that a capa¬ 
bility is missing from this terminal. Note that this format corresponds to the 
hardware of the VAX and PDP-11. Machines where this does not correspond to the 
hardware read the integers as two bytes and compute the result. 

The terminal names section comes next. It contains the first line of the terminfo 
description, listing the various names for the terminal, separated by the character. 
The section is terminated with an ASCII NUL character. 

The boolean flags have one byte for each flag. This byte is either 0 or 1 as the flag is 
present or absent. The capabilities are in the same order as the file <term.h>. 
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Between the boolean section and the number section, a null byte will be inserted, if 
necessary, to ensure that the number section begins on an even byte. All short 
integers are aligned on a short word boundary. 

The numbers section is similar to the flags section. Each capability takes up two 
bytes, and is stored as a short integer. If the value represented is —1, the capability 
is taken to be missing. 

The strings section is also similar. Each capability is stored as a short integer, in 
the format above. A value of —1 means the capability is missing. Otherwise, the 
value is taken as an offset from the beginning of the string table. Special characters 
in A X or \c notation are stored in their interpreted form, not the printing represen¬ 
tation. Padding information $<nn> and parameter information %x are stored 
intact in uninterpreted form. 

The final section is the string table. It contains all the values of string capabilities 
referenced in the string section. Each string is null terminated. 

Note that it is possible for setupterm to expect a different set of capabilities than are 
actually present in the file. Either the database may have been updated since setup- 
term has been recompiled (resulting in extra unrecognized entries in the file) or the 
program may have been recompiled more recently than the database was updated 
(resulting in missing entries). The routine setupterm must be prepared for both pos¬ 
sibilities — this is why the numbers and sizes are included. Also, new capabilities 
must always be added at the end of the lists of boolean, number, and string capabili¬ 
ties. 


As an example, an octal dump of the description for the Microterm ACT 4 is 
included: 

microterm|act4jmicroterm act iv, 

cr="M, cudl='J, ind= A J, bel= A G, am, cubl= A H, 
ed= A _, el= AA , clear= A L, cup= A T%pl%c%p2%c, 
cols#80, lines#24, cufl='X, cuul= A Z, home= A ], 

000 032 001 \0 025 \0 \b \0 212 \0 " \0 m i c r 

020 oterm|act4jmicro 
040 term act iv\0\0 001 \0 \0 
060 \0 \0 \0 \0 \0 \0 \0 \0 \0 \0 \0 \0 \0 \0 \0 \0 
100 \0 \0 P \0 377 377 030 \0 377 377 377 377 377 377 377 377 
120 377 377 377 377 \0 \0 002 \0 377 377 377 377 004 \0 006 \0 
140 \b \0 377 377 377 377 \n \0 026 \0 030 \0 377 377 032 \0 
160 377 377 377 377 034 \0 377 377 036 \0 377 377 377 377 377 377 
200 377 377 377 377 377 377 377 377 377 377 377 377 377 377 377 377 
* 

520 377 377 377 377 \0 377 377 377 377 377 377 377 377 377 377 

540 377 377 377 377 377 377 007 \0 \r \0 \f \0 036 \0 037 \0 
560 024 % p 1 % c % p 2 % c \0 \n \0 035 \0 
600 \b \0 030 \0 032 \0 \n \0 


2 


Icon International. Inc. 



TERM (4) 


FILE FORMATS 


Some limitations: total compiled entries cannot exceed 4096 bytes, 
cannot exceed 128 bytes. 


FILES 


/usr/lib/terminfo/*/*compiled terminal capability data base 


SEE ALSO 

curses(3X), terminfo(4). 


TERM (4) 

The name field 
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NAME 

termcap — terminal capability data base 


SYNOPSIS 

/etc/termcap 


DESCRIPTION 

Termcap is a data base describing terminals, used, e.g ., by tu(l) and curses(3X). 
Terminals are described in termcap by giving a set of capabilities which they have, 
and by describing how operations are performed. Padding requirements and initiali¬ 
zation sequences are included in termcap. 

Entries in termcap consist of a number of separated fields. The first entry for each 
terminal gives the names which are known for the terminal, separated by ‘J’ charac¬ 
ters. The first name is always 2 characters long and is used by older version 6 sys¬ 
tems which store the terminal type in a 16 bit word in a systemwide data base. The 
second name given is the most common abbreviation for the terminal, and the last 
name given should be a long name fully identifying the terminal. The second name 
should contain no blanks; the last name may well contain blanks for readability. 


CAPABILITIES 

(P) indicates padding may be specified 

(P*) indicates that padding may be based on no. lines affected 

Name Type Pad? Description 


ae 

str 

(P) 

End alternate character set 

al 

str 

(P*) 

Add new blank line 

am 

bool 

Terminal has automatic margins 

as 

str 

(P) 

Start alternate character set 

be 

str 

Backspace if not A H 

bs 

bool 


Terminal can backspace with A H 

bt 

str 

(P) 

Back tab 

bw 

bool 

Backspace wraps from column 0 to 
last column 

CC 

str 


Command character in prototype if 
terminal settable 

cd 

str 

(P*) 

Clear to end of display 

ce 

str 

(P) 

Clear to end of line 

ch 

str 

(P) 

Like cm but horizontal motion only, 
line stays same 

cl 

str 

(P*) 

Clear screen 

cm 

str 

(P) 

Cursor motion 

CO 

num 

Number of columns in a line 

cr 

str 

(P*) 

Carriage return, (default A M) 
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cs 

str 

(P) 

Change scrolling region (vtlOO), like cm 

cv 

str 

(P) 

Like ch but vertical only. 

da 

bool 

Display may be retained above 

dB 

num 


Number of millisec of bs delay needed 

db 

bool 


Display may be retained below 

dC 

num 


Number of millisec of cr delay needed 

dc 

str 

(P*) 

Delete character 

dF 

num 

Number of millisec of ff delay needed 

dl 

str 

(P*) 

Delete line 

dm 

str 

Delete mode (enter) 

dN 

num 


Number of millisec of nl delay needed 

do 

str 


Down one line 

dT 

num 


Number of millisec of tab delay needed 

ed 

str 


End delete mode 

ei 

str 


End insert mode; give “:ei=:” if ic 

eo 

str 


Can erase overstrikes with a blank 

ff 

str 

(P*) 

Hardcopy terminal page eject (default 

*L) 

he 

bool 


Hardcopy terminal 

hd 

str 


Half-line down (forward 1/2 linefeed) 

ho 

str 


Home cursor (if no cm) 

hu 

str 


Half-line up (reverse 1/2 linefeed) 

Hazeltine; can’t print ~’s 

hz 

str 


ic 

str 

(P) 

Insert character 

if 

str 

Name of file containing is 

im 

bool 


Insert mode (enter); give “:im=:” if 

ic 

Insert mode distinguishes nulls on 
display 

in 

bool 


ip 

str 

(P*) 

Insert pad after character inserted 

is 

str 

Terminal initialization string 

k0-k9 

str 


Sent by “other” function keys 0-9 

kb 

str 


Sent by backspace key 

kd 

str 


Sent by terminal down arrow key 

ke 

str 


Out of “keypad transmit” mode 

kh 

str 


Sent by home key 

kl 

str 


Sent by terminal left arrow key 

kn 

num 


Number of “other” keys 

ko 

str 


Termcap entries for other non-function keys 

kr 

str 


Sent by terminal right arrow key 

ks 

str 


Put terminal in “keypad transmit” mode 

ku 

str 


Sent by terminal up arrow key 

10-19 

str 


Labels on “other” function keys 

li 

num 


Number of lines on screen or page 

11 

str 


Last line, first column (if no cm) 

ma 

str 


Arrow key map, used by vi version 2 
only 

mi 

bool 


Safe to move while in insert mode 

ml 

str 


Memory lock on above cursor. 

ms 

bool 


Safe to move while in standout and 
underline mode 

mu 

str 


Memory unlock (turn off memory lock). 

nc 

bool 


No correctly working carriage return 
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(DM2500, H2000) 

nd 

str 


Non-destructive space (cursor right) 

nl 

str 

(P*) 

Newline character (default \n) 

ns 

bool 

Terminal is a CRT but doesn’t scroll. 

os 

bool 


Terminal overstrikes 

pc 

str 


Pad character (rather than null) 

pt 

bool 


Has hardware tabs (may need to be set 
with is) 

se 

str 


End stand out mode 

sf 

str 

(P) 

Scroll forwards 

sg 

num 

Number of blank chars left by so or se 

so 

str 


Begin stand out mode 

sr 

str 

(P) 

Scroll reverse (backwards) 

Tab (other than *1 or with padding) 

ta 

str 

(P) 

tc 

str 


Entry of similar terminal - must be last 

te 

str 


String to end programs that use cm 

ti 

str 


String to begin programs that use cm 

uc 

str 


Underscore one char and move past it 

ue 

str 


End underscore mode 

ug 

num 


Number of blank chars left by us or ue 

ul 

bool 


Terminal underlines even though it 
doesn’t overstrike 

up 

str 


Upline (cursor up) 

us 

str 


Start underscore mode 

vb 

str 


Visible bell (may not move cursor) 

ve 

str 


Sequence to end open/visual mode 

vs 

str 


Sequence to start open/visual mode 

xb 

bool 


Beehive (fl=escape, f2=ctrl C) 

xn 

bool 


A newline is ignored after a wrap 
(Concept) 

xr 

bool 


Return acts like ce \r \n 
(Delta Data) 

xs 

bool 


Standout not erased by writing oveT 
it (HP 264?) 

xt 

bool 


Tabs are destructive, magic so chaT 
(Teleray 1061) 

A Sample Entry 



The following entry, which describes the Concept—100, is among the more complex 
entries in the termcap file as of this writing. (This particular concept entry is out¬ 
dated, and is used as an example only.) 

cl JclOO j concept 100:is=\EU\Ef\E7\E5\E8\El\ENH\EK\E\200\Eo&\200:\ 

:al=3*\E"R:am:bs:cd=16*\E"C:ce=16\E"S:cl=2*"L:cm=\Ea%+ %+ :co#80:\ 
:dc=16\E'A:dl=3*\E*B:ei=\E\200:eo:im=\E~P:in:ip=16*:li#24:mi:nd=\E=:\ 

:se =\Ed \Ee :so=\ED\EE: t a ==8 \t: ul: up=\E;: v b=\Ek \EI< :xn: 

Entries may continue onto multiple lines by giving a \ as the last character of a line, 
and that empty fields may be included for readability (here between the last field on 
a line and the first field on the next). Capabilities in termcap are of three types: 
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Boolean capabilities which indicate that the terminal has some particular feature, 
numeric capabilities giving the size of the terminal or the size of particular delays, 
and string capabilities, which give a sequence which can be used to perform particu¬ 
lar terminal operations. 

Types of Capabilities 

All capabilities have two letter codes. For instance, the fact that the Concept has 
“automatic margins” (i.e. an automatic return and linefeed when the end of a line is 
reached) is indicated by the capability am. Hence the description of the Concept 
includes am. Numeric capabilities are followed by the character ‘#’ and then the 
value. Thus co which indicates the number of columns the terminal has gives the 
value ‘80’ for the Concept. 


Finally, string valued capabilities, such as ce (clear to end of line sequence) are given 
by the two character code, an *=’, and then a string ending at the next following 
A delay in milliseconds may appear after the '=’ in such a capability, and padding 
characters are supplied by the editor after the remainder of the string is sent, to pro¬ 
vide this delay. The delay can be either a integer, e.g. ‘20’, or an integer followed by 
an V, i.e. ‘3*’. A V indicates that the padding required is proportional to the 
number of lines affected by the operation, and the amount given is the per-affected- 
unit padding required. When a V is specified, it is sometimes useful to give a delay 
of the form ‘3.5’ specify a delay per unit to tenths of milliseconds. 

A number of escape sequences are provided in the string valued capabilities for easy 
encoding of characters there. A \E maps to an ESCAPE character, ‘x maps to a 
control-x for any appropriate x, and the sequences \n \r \t \b \f give a newline, 
return, tab, backspace and formfeed. Finally, characters may be given as three 
octal digits after a \, and the characters ' and \ may be given as \* and w If it is 
necessary to place a : in a capability it must be escaped in octal as \072. If it is 
necessary to place a null character in a string capability it must be encoded as \200 
The routines which deal with termcap use C strings, and strip the high bits of the 
output very late so that a \200 comes out as a \000 would. 

Preparing Descriptions 

We now outline how to prepare descriptions of terminals. The most effective way to 
prepare a terminal description is by imitating the description of a similar terminal in 
termcap and to build up a description gradually, using partial descriptions with ex to 
check that they are correct. Be aware that a very unusual terminal may expose 
deficiencies in the ability of the termcap file to describe it or bugs in ex. To easily 
test a new terminal description you can set the environment variable TERMCAP to 
a pathname of a file containing the description you are working on and the editor 
will look there rather than in /etc/termcap. TERMCAP can also be set to the 
termcap entry itself to avoid reading the file when starting up the editor. (This only 
works on version 7 systems.) 

Basic capabilities 
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The number of columns on each line for the terminal is given by the co numeric 
capability. If the terminal is a CRT, then the number of lines on the screen is given 
by the li capability. If the terminal wraps around to the beginning of the next line 
when it reaches the right margin, then it should have the am capability. If the ter¬ 
minal can clear its screen, then this is given by the cl string capability. If the termi¬ 
nal can backspace, then it should have the bs capability, unless a backspace is 
accomplished by a character other than *H (ugh) in which case you should give this 
character as the be string capability. If it overstrikes (rather than clearing a posi¬ 
tion when a character is struck over) then it should have the os capability. 

A very important point here is that the local cursor motions encoded in termcap are 
undefined at the left and top edges of a CRT terminal. The editor will never attempt 
to backspace around the left edge, nor will it attempt to go up locally off the top. 
The editor assumes that feeding off the bottom of the screen will cause the screen to 
scroll up, and the am capability tells whether the cursor sticks at the right edge of 
the screen. If the terminal has switch selectable automatic margins, the termcap file 
usually assumes that this is on, i.e. am. 

These capabilities suffice to describe hardcopy and “glass-tty” terminals. Thus the 
model 33 teletype is described as 

t3133' tty33:co#72:os 

while the Lear Siegler ADM-3 is described as 

cl[adm3|3jlsi adm3:am:bs:cl=~Z:li#24:co#80 

Cursor addressing 

Cursor addressing in the terminal is described by a cm string capability, with 
printf{ 3S) like escapes %x in it. These substitute to encodings of the current line or 
column position, while other characters are passed through unchanged. If the cm 
string is thought of as being a function, then its arguments are the line and then the 
column to which motion is desired, and the % encodings have the following mean¬ 
ings: 


%d 

as in printf, 0 origin 

%2 

like %2d 

%3 

like %3d 

%. 

like %c 

%+x 

adds x to value, then %. 

%>xy 

if value > x adds y, no output. 

%r 

reverses order of line and column, 
no output 

%i 

increments line/column (for 1 origin) 

%% 

gives a single % 

%a 

exclusive or row and column with 0140 
(DM2500) 

%B 

BCD (16*(x/l0)) + (x%10), no output. 
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%D Reverse coding (x-2*(x%16)), no output. 

(Delta Data). 

Consider the HP2645, which, to get to row 3 and column 12, needs to be sent 
\E&al2c03Y padded for 6 milliseconds. Note that the order of the rows and 
columns is inverted here, and that the row and column are printed as two digits. 
Thus its cm capability is “cm=6\E&%r%2c%2Y”. The Microterm ACT-IV needs the 
current row and column sent preceded by a *T, with the row and column simply 
encoded in binary, “cm=*T%.%.”. Terminals which use need to be able to 

backspace the cursor (bs or be), and to move the cursor up one line on the screen 
(up introduced below). This is necessary because it is not always safe to transmit 
V> \n ' k D and \r, as the system may change or discard them. 

A final example is the LSI ADM-3a, which uses row and column offset by a blank char¬ 
acter, thus “cm=\E=%+ %+ ”. 

Cursor motions 

If the terminal can move the cursor one position to the right, leaving the character 
at the current position unchanged, then this sequence should be given as nd (non¬ 
destructive space). If it can move the cursor up a line on the screen in the same 
column, this should be given as up. If the terminal has no cursor addressing capabil¬ 
ity, but can home the cursor (to very upper left corner of screen) then this can be 
given as ho; similarly a fast way of getting to the lower left hand corner can be 
given as 11; this may involve going up with up from the home position, but the editor 
will never do this itself (unless 11 does) because it makes no assumption about the 
effect of moving up from the home position. 

Area clears 

If the terminal can clear from the current position to the end of the line, leaving the 
cursor where it is, this should be given as ce. If the terminal can clear from the 
current position to the end of the display, then this should be given as cd. The edi¬ 
tor only uses cd from the first column of a line. 

Insert /delete line 

If the terminal can open a new blank line before the line where the cursor is, this 
should be given as al; this is done only from the first position of a line. The cursor 
must then appear on the newly blank line. If the terminal can delete the line which 
the cursor is on, then this should be given as dl; this is done only from the first posi¬ 
tion on the line to be deleted. If the terminal can scroll the screen backwards, then 
this can be given as sb, but just al suffices. If the terminal can retain display 
memory above then the da capability should be given; if display memory can be 
retained below then db should be given. These let the editor understand that delet¬ 
ing a line on the screen may bring non-blank lines up from below or that scrolling 
back with sb may bring down non-blank lines. 
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Insert/delete character 

There are two basic kinds of intelligent terminals with respect to insert/delete char¬ 
acter which can be described using termcap. The most common insert/delete charac¬ 
ter operations affect only the characters on the current line and shift characters off 
the end of the line rigidly. Other terminals, such as the Concept 100 and the Perkin 
Elmer Owl, make a distinction between typed and untyped blanks on the screen, 
shifting upon an insert or delete only to an untyped blank on the screen which is 
either eliminated, or expanded to two untyped blanks. You can find out which kind 
of terminal you have by clearing the screen and then typing text separated by cursor 
motions. Type “abc def” using local cursor motions (not spaces) between the 
“abc” and the “def”. Then position the cursor before the “abc” and put the termi¬ 
nal in insert mode. If typing characters causes the rest of the line to shift rigidly 
and characters to fall off the end, then your terminal does not distinguish between 
blanks and untyped positions. If the “abc” shifts over to the “def” which then move 
together around the end of the current line and onto the next as you insert, you have 
the second type of terminal, and should give the capability in, which stands for 
“insert null”. If your terminal does something different and unusual then you may 
have to modify the editor to get it to use the insert mode your terminal defines. We 
have seen no terminals which have an insert mode not not falling into one of these 
two classes. 

The editor can handle both terminals which have an insert mode, and terminals 
which send a simple sequence to open a blank position on the current line. Give as 
im the sequence to get into insert mode, or give it an empty value if your terminal 
uses a sequence to insert a blank position. Give as ei the sequence to leave insert 
mode (give this, with an empty value also if you gave im so). Now give as ic any 
sequence needed to be sent just before sending the character to be inserted. Most 
terminals with a true insert mode will not give ic, terminals which send a sequence 
to open a screen position should give it here. (Insert mode is preferable to the 
sequence to open a position on the screen if your terminal has both.) If post insert 
padding is needed, give this as a number of milliseconds in ip (a string option). Any 
other sequence which may need to be sent after an insert of a single character may 
also be given in ip. 

It is occasionally necessary to move around while in insert mode to delete characters 
on the same line (e.g. if there is a tab after the insertion position). If your terminal 
allow's motion while in insert mode you can give the capability mi to speed up insert¬ 
ing in this case. Omitting mi will affect only speed. Some terminals (notably 
Datamedia’s) must not have mi because of the way their insert mode works. 

Finally, you can specify delete mode by giving dm and ed to enter and exit delete 
mode, and dc to delete a single character while in delete mode. 


Highlighting, underlining, and visible bells 

If your terminal has sequences to enter and exit standout mode these can be given as 
so and se respectively. If there are several flavors of standout mode (such as inverse 
video, blinking, or underlining — half bright is not usually an acceptable “standout” 
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mode unless the terminal is in inverse video mode constantly) the preferred mode is 
inverse video by itself. If the code to change into or out of standout mode leaves one 
or even two blank spaces on the screen, as the TVI 912 and Teleray 1061 do, then 
ug should be given to tell how many spaces are left. 

Codes to begin underlining and end underlining can be given as us and ue respec¬ 
tively. If the terminal has a code to underline the current character and move the 
cursor one space to the right, such as the Microterm Mime, this can be given as uc. 
(If the underline code does not move the cursor to the right, give the code followed 
by a nondestructive space.) 

Many terminals, such as the HP 2621, automatically leave standout mode when they 
move to a new line or the cursor is addressed. Programs using standout mode should 
exit standout mode before moving the cursor or sending a newline. 

If the terminal has a way of flashing the screen to indicate an error quietly (a bell 
replacement) then this can be given as vb; it must not move the cursor. If the ter¬ 
minal should be placed in a different mode during open and visual modes of ex, this 
can be given as vs and ve, sent at the start and end of these modes respectively. 
These can be used to change, e.g., from a underline to a block cursor and back. 

If the terminal needs to be in a special mode when running a program that addresses 
the cursor, the codes to enter and exit this mode can be given as ti and te. This 
arises, for example, from terminals like the Concept with more than one page of 
memory. If the terminal has only memory relative cursor addressing and not screen 
relative cursor addressing, a one screen-sized window must be fixed into the terminal 
for cursor addressing to work properly. 

If your terminal correctly generates underlined characters (with no special codes 
needed) even though it does not overstrike, then you should give the capability ul. If 
overstrikes are erasable with a blank, then this should be indicated by giving eo. 

Keypad 

If the terminal has a keypad that transmits codes when the keys are pressed, this 
information can be given. Note that it is not possible to handle terminals where the 
keypad only works in local (this applies, for example, to the unshifted HP 2621 keys). 
If the keypad can be set to transmit or not transmit, give these codes as ks and ke. 
Otherwise the keypad is assumed to always transmit. The codes sent by the left 
arrow, right arrow, up arrow, down arrow, and home keys can be given as kl, kr, 
ku, kd, and kh respectively. If there are function keys such as fO, fl, ..., f9, the 
codes they send can be given as kO, kl, ..., k9. If these keys have labels other than 
the default fO through f9, the labels can be given as 10, 11, ..., 19. If there are other 
keys that transmit the same code as the terminal expects for the corresponding 
function, such as clear screen, the termcap 2 letter codes can be given in the ko 
capability, for example, “:ko=cl,ll,sf,sb:”, which says that the terminal has clear, 
home down, scroll down, and scroll up keys that transmit the same thing as the cl, 11, 
sf, and sb entries. 
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The ma entry is also used to indicate arrow keys on terminals which have single 
character arrow keys. It is obsolete but still in use in version 2 of vi, which must be 
run on some minicomputers due to memory limitations. This field is redundant with 
kl, kr, ku, kd, and kh. It consists of groups of two characters. In each group, the 
first character is what an arrow key sends, the second character is the corresponding 
vi command. These commands are h for kl, j for kd, k for ku, 1 for kr, and H for 
kh. For example, the mime would be :ma—*Kj*Zk‘Xl: indicating arrow keys left 
( A H), down ( A K), up ( A Z), and right ( A X). (There is no home key on the mime.) 

Miscellaneous 

If the terminal requires other than a null (zero) character as a pad, then this can be 
given as pc. 

If tabs on the terminal require padding, or if the terminal uses a character other 
than A I to tab, then this can be given as ta. 

Hazeltine terminals, which don’t allow characters to be printed should indicate 
hz. Datamedia terminals, which echo carriage-return linefeed for carriage return 
and then ignore a following linefeed should indicate nc. Early Concept terminals, 
which ignore a linefeed immediately after an am wrap, should indicate xn. If an 
erase-eol is required to get rid of standout (instead of merely writing on top of it), xs 
should be given. Teleray terminals, where tabs turn all characters moved over to 
blanks, should indicate xt. Other specific terminal problems may be corrected by 
adding more capabilities of the form xt. 

Other capabilities include is, an initialization string for the terminal, and if, the 
name of a file containing long initialization strings. These strings are expected to 
properly clear and then set the tabs on the terminal, if the terminal has settable 
tabs. If both are given, is will be printed before if. This is useful where if is 
/usr/lib/tabset/std but is clears the tabs first. 

Similar Terminals 

If there are two very similar terminals, one can be defined as being just like the 
other with certain exceptions. The string capability tc can be given with the name 
of the similar terminal. This capability must be last and the combined length of the 
two entries must not exceed 1024. Since termlib routines search the entry from left to 
right, and since the tc capability is replaced by the corresponding entry, the capabil¬ 
ities given at the left override the ones in the similar terminal. A capability can be 
canceled with xx@ where xx is the capability. For example, the entry 


hn j2621nl:ks@;ke@;tc=2621: 

defines a 2621nl that does not have the ks or ke capabilities, and hence does not 
turn on the function key labels when in visual mode. This is useful for different 
modes for a terminal, or for different user preferences. 


Icon International, Inc. 


9 



TERMCAP (4) 


FILE FORMATS 


TERMCAP (4) 


FILES 


/etc/termcap file containing terminal descriptions 


SEE ALSO 

ex(l), curses(3X), vi(l), more(l) 


AUTHOR 

William Joy 

Mark Horton added underlining and keypad support 


BUGS 


Ex allows only 256 characters for string capabilities, and the routines in curses( 3X) 
do not check for overflow of this buffer. The total length of a single entry (excluding 
only escaped newlines) may not exceed 1024. 

The ma, vs, and ve entries are specific to the vi program. 

Not all programs support all entries. There are entries that are not supported by 
any program. 
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NAME 

terminfo — terminal capability data base 


SYNOPSIS 

/usr/lib/terminfo/*/* 


DESCRIPTION 

Terminfo is a data base describing terminals, used, e.g.,, by vi( 1) and curses( 3X). 
Terminals are described in terminfo by giving a set of capabilities which they have, 
and by describing how operations are performed. Padding requirements and initiali¬ 
zation sequences are included in terminfo. 

Entries in terminfo consist of a number of V separated fields. White space after each 
V is ignored. The first entry for each terminal gives the names which are known for 
the terminal, separated by ‘j’ characters. The first name given is the most common 
abbreviation for the terminal, the last name given should be a long name fully iden¬ 
tifying the terminal, and all others are understood as synonyms for the terminal 
name. All names but the last should be in lower case and contain no blanks; the last 
name may well contain upper case and blanks for readability. 

Terminal names (except for the last, verbose entry) should be chosen using the fol¬ 
lowing conventions. The particular piece of hardware making up the terminal should 
have a root name chosen, thus “hp2621”. This name should not contain hyphens, 
except that synonyms may be chosen that do not conflict with other names. Modes 
that the hardware can be in, or user preferences, should be indicated by appending a 
hyphen and an indicator of the mode. Thus, a vtlOO in 132 column mode would be 
vtlOO-w. The following suffixes should be used where possible: 


Suffix 

Meaning 

Example 

-w 

Wide mode (more than 80 columns) 

vtlOO-w 

-am 

With auto, margins (usually default) 

vtlOO-am 

-nam 

Without automatic margins 

vtlOO-nam 

-n 

Number of lines on the screen 

aaa-60 

-na 

No arrow keys (leave them in local) 

clOO-na 

-np 

Number of pages of memory 

cl00-4p 

-rv 

Reverse video 

clOO-rv 


CAPABILITIES 

The variable is the name by which the programmer (at the terminfo level) accesses 
the capability. The capname is the short name used in the text of the database, and 
is used by a person updating the database. The i.code is the two letter internal code 
used in the compiled database, and always corresponds to the old termcap capabil¬ 
ity name. Capability names have no hard length limit, but an informal limit of 5 
characters has been adopted to keep them short and to allow the tabs in the source 
file caps to line up nicely. Whenever possible, names are chosen to be the same as 
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or similar to the ANSI X3.64-1979 standard. Semantics are also intended to match 
those of the specification. 

(P) indicates that padding may be specified 

(G) indicates that the string is passed through tparm withparms as given (#i). 

(*) indicates that padding may be based on the number of lines affected 


(# | ) indicates the parameter. 


Variable 

Cap- 

L 

Booleans 

name 

Code 

autoJeft_margin, 

bw 

bw 

auto_righ tjaargin, 

am 

am 

beehive_glitch, 

xsb 

xb 

ceoLstandout_glitch, 

xhp 

xs 

eat_newline_glitch, 

xenl 

xn 

er ase_overst rik e, 

eo 

eo 

generic_type, 

gn 

gn 

hard-copy, 

he 

he 

has_meta_key, 

km 

km 

has.j5tatus.Jine, 

hs 

hs 

insert_null_glitch, 

in 

in 

memory ..above, 

da 

da 

memory _below, 

db 

db 

move_jnsert_mode, 

mir 

mi 

move_standout_mode, 

msgr 

ms 

overjstrike, 

os 

os 

statusJine_esc_ok, 

eslok 

es 

teleray_glitch, 

xt 

xt 

tilde_glitch, 

hz 

hz 

transparent_underline, 

ul 

ul 

xon/xoff, 

xon 

xo 

Numbers: 

columns, 

cols 

CO 

init_tabs, 

it 

it 

lines, 

lines 

li 

lines_of.jnemory, 

lm 

lm 

magic_cookie_glitch, 

xmc 

sg 

padding_baudLrate, 

pb 

Pb 

virtuaLterminal, 

vt 

vt 

width_j5tatus_line, 

wsl 

ws 

Strings: 

back_tab, 

cbt 

bt 

bell, 

bel 

bl 

carriagejreturn, 

cr 

cr 

change jscrolLregion, 

csr 

cs 

clear_alLtabs, 

tbc 

ct 

clearjscreen, 

clear 

cl 

clr_eol, 

el 

ce 

clr_eos, 

ed 

cd 

col u mn_address, 

hpa 

ch 


Description 

cubl wraps from column 0 to last column 
Terminal has automatic margins 
Beehive (fl=escape, f2=ctrl C) 

Standout not erased by overwriting (hp) 
newline ignored after 80 cols (Concept) 

Can erase overstrikes with a blank 
Generic line type (e.g.,, dialup, switch). 
Hardcopy terminal 

Has a meta key (shift, sets parity bit) 

Has extra "status line" 

Insert mode distinguishes nulls 
Display may be retained above the screen 
Display may be retained below the screen 
Safe to move while in insert mode 
Safe to move in standout modes 
Terminal overstrikes 
Escape can be used on the status line 
Tabs ruin, magic so char (Teleray 1061) 
Hazeltine; can not print ~’s 
underline character overstrikes 
Terminal uses xon/xoff handshaking 

Number of columns in a line 

Tabs initially every # spaces 

Number of lines on screen or page 

Lines of memory if > lines. 0 means varies 

Number of blank chars left by smso or rmso 

Lowest baud where cr/nl padding is needed 

Virtual terminal number (UNIX system) 

No. columns in status line 


Back tab (P) 

Audible signal (bell) (P) 

Carriage return (P*) 

change to lines #1 through #2 (vtlOO) (PG) 
Clear all tab stops (P) 

Clear screen and home cursor (P*) 

Clear to end of line (P) 

Clear to end of display (P*) 

Set cursor column (PG) 


2 


Icon International, Inc. 


TERMINFO (4) 


commancL.character, 

cursor_address, 

cursor_down, 

cursorJ^ome, 

cursorJnvisible, 

cursorjeft, 

cursor_mem_address, 

cursor_normal, 

cursor«j*ight, 

cursor^tojl, 

cursor^up, 

cursor_visible, 

delete_character, 

deletejine, 

dis_statusjine, 

dowaJialfJine, 

en tergal t_charset_mode, 

enter_blink_jnode, 

enterJt>olcLmode, 

enter_ca_mode, 

enter_delete_mode, 

enter_dim_mode, 

enter_insert_mode, 

enter_protected„mode, 

enter_reverse_mode, 

enter_secure_mode, 

en ter^tandout_jnode, 

enter«junderline_mode, 

erase_chars 

exit_alt_charset„jnode, 

exit^att ribute^mode, 

exit_ca_mode, 

exit_delete_mode, 

exit_insert_mode, 

exit_standout_mode, 

exi t_underline_mode, 

flashuscreen, 

formJeed, 

fronustatusjine, 

init_lstring, 

init_2string, 

iniOstring, 

initjfile, 

insert_character, 

insert Jine, 

insert_padding, 

key_backspace, 

key_catab, 

key_clear, 

key _c tab, 

key.dc, 

key_dl, 

key_down, 
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cmdch 

CC 

Term, settable cmd char in prototype 

cup 

cm 

Screen rei. cursor motion row #1 col #2 (PG) 

cudl 

do 

Down one line 

home 

ho 

Home cursor (if no cup) 

civis 

vi 

Make cursor invisible 

cubl 

le 

Move cursor left one space 

mrcup 

CM 

Memory relative cursor addressing 

cnorm 

ve 

Make cursor appear normal (undo vs/vi) 

cufl 

nd 

Non-destructive space (cursor right) 

11 

11 

Last line, first column (if no cup) 

cuul 

up 

Upline (cursor up) 

cwis 

vs 

Make cursor very visible 

dchl 

dc 

Delete character (P*) 

dll 

dl 

Delete line (P*) 

dsl 

ds 

Disable status line 

hd 

hd 

Half-line down (forward 1/2 linefeed) 

smacs 

as 

Start alternate character set (P) 

blink 

mb 

Turn on blinking 

bold 

md 

Turn on bold (extra bright) mode 

smcup 

ti 

String to begin programs that use cup 

smdc 

dm 

Delete mode (enter) 

dim 

mh 

Turn on half-bright mode 

smir 

im 

Insert mode (enter); 

prot 

mp 

Turn on protected mode 

rev 

mr 

Turn on reverse video mode 

invis 

mk 

Turn on blank mode (chars invisible) 

smso 

so 

Begin stand out mode 

smul 

us 

Start underscore mode 

ech 

ec 

Erase #1 characters (PG) 

rmacs 

ae 

End alternate character set (P) 

sgrO 

me 

Turn off all attributes 

rmcup 

te 

String to end programs that use cup 

rmdc 

ed 

End delete mode 

rmir 

ei 

End insert mode 

rmso 

se 

End stand out mode 

rmul 

ue 

End underscore mode 

flash 

vb 

Visible bell (may not move cursor) 

ff 

ff 

Hardcopy terminal page eject (P*) 

fsl 

fs 

Return from status line 

isl 

il 

Terminal initialization string 

is2 

i2 

Terminal initialization string 

is3 

i3 

Terminal initialization string 

if 

if 

Name of file containing is 

ichl 

ic 

Insert character (P) 

ill 

al 

Add new blank line (P*) 

ip 

ip 

Insert pad after character inserted (P*) 

kbs 

kb 

Sent by backspace key 

ktbc 

ka 

Sent by clear-all-tabs key 

kclr 

kC 

Sent by clear screen or erase key 

kctab 

kt 

Sent by clear-tab key 

kdchl 

kD 

Sent by delete character key 

kdll 

kL 

Sent by delete line key 

kcudl 

kd 

Sent by terminal down arrow key 
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key_eic, 

krmir 

kM 

key_eol, 

kel 

kE 

key_eos, 

ked 

kS 

key_/0, 

kfO 

kO 

key_fl, 

kfl 

kl 

key_flO, 

kflO 

ka 

key_f2, 

kf2 

k2 

key_f3, 

kf3 

k3 

key_f4, 

kf4 

k4 

key_f5, 

kf5 

k5 

key_f6, 

kf6 

k6 

key_f7, 

kf7 

k7 

key_f8, 

kf8 

k8 

key_f9, 

kf9 

k9 

key_home, 

khome 

kh 

keyjc, 

kichl 

kl 

key_il, 

kill 

kA 

keyjeft, 

kcubl 

kl 

key_ll, 

kll 

kH 

key_npage, 

knp 

kN 

key_ppage, 

kpp 

kP 

key_right, 

kcufl 

kr 

key_sf, 

kind 

kF 

key_sr, 

kri 

kR 

key_stab, 

khts 

kT 

key_up, 

kcuul 

ku 

keypadjocal, 

rmkx 

ke 

keypad_xmit, 

smkx 

ks 

lab_fO, 

lfO 

10 

lab_fl, 

lfl 

11 

lab_flO, 

lflO 

la 

lab_f2, 

lf2 

12 

lab_f3, 

lf3 

13 

lab_X4, 

lf4 

14 

lab_f5, 

lf5 

15 

lab_f6, 

lf6 

16 

labJ7, 

lf7 

17 

lab_f8, 

lf8 

18 

lab_f9, 

lf9 

19 

meta_on, 

smm 

mm 

meta_off, 

rmm 

mo 

newline, 

nel 

nw 

pad_char, 

pad 

pc 

parm_dch, 

dch 

DC 

parm_delete_line, 

dl 

DL 

parm_down_cursor, 

cud 

DO 

parm_ich, 

ich 

IC 

parm_index, 

indn 

SF 

par m_insert Jiine, 

il 

AL 

par m_left_cursor, 

cub 

LE 

parm_right_cursor, 

cuf 

RI 

parm_rindex, 

rin 

SR 

parm_up_cursor, 

cuu 

UP 


Sent by rmir or smir in insert mode 

Sent by clear-to-end-of-line key 

Sent by clear-to-end-of-screen key 

Sent by function key fO 

Sent by function key fl 

Sent by function key flO 

Sent by function key f2 

Sent by function key f3 

Sent by function key f4 

Sent by function key f5 

Sent by function key f6 

Sent by function key f7 

Sent by function key f8 

Sent by function key f9 

Sent by home key 

Sent by ins char/enter ins mode key 

Sent by insert line 

Sent by terminal left arrow key 

Sent by home-down key 

Sent by next-page key 

Sent by previous-page key 

Sent by terminal right arrow key 

Sent by scroll-forward/down key 

Sent by scroll-backward/up key 

Sent by set-tab key 

Sent by terminal up arrow key 

Out of ’’keypad transmit” mode 

Put terminal in "keypad transmit” mode 

Labels on function key fO if not fO 

Labels on function key fl if not fl 

Labels on function key flO if not flO 

Labels on function key f2 if not f2 

Labels on function key f3 if not f3 

Labels on function key f4 if not f4 

Labels on function key f5 if not f5 

Labels on function key f6 if not f6 

Labels on function key f7 if not f7 

Labels on function key f8 if not f8 

Labels on function key f9 if not f9 

Turn on ”meta mode” (8th bit) 

Turn off ”meta mode” 

Newline (behaves like cr followed by If) 
Pad character (rather than null) 

Delete #1 chars (PG*) 

Delete #1 lines (PG*) 

Move cursor down #1 lines (PG*) 

Insert #1 blank chars (PG*) 

Scroll forward #1 lines (PG) 

Add #1 new blank lines (PG*) 

Move cursor left #1 spaces (PG) 

Move cursor right #1 spaces (PG*) 

Scroll backward #1 lines (PG) 

Move cursor up #1 lines (PG*) 
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pkeyjcey, 

pfkey 

Pk 

Prog funct key #1 to type string #2 

pkeyjocal, 

pfloc 

Pi 

Prog funct key #1 to execute string #2 

pkey_xmit, 

pfx 

px 

Prog funct key #1 to xmit string #2 

print_screen, 

mcO 

ps 

Print contents of the screen 

prtr_off, 

mc4 

Pf 

Turn off the printer 

prtr_on, 

me 5 

po 

Turn on the printer 

repeat_char, 

rep 

r p 

Repeat char #1 #2 times. (PG*) 

reset_lstring, 

rsl 

rl 

Reset terminal completely to sane modes. 

reset_2string, 

rs2 

r2 

Reset terminal completely to sane modes. 

reset_3string, 

rs3 

r3 

Reset terminal completely to sane modes. 

resetJMe, 

rf 

rf 

Name of file containing reset string 

restore_cursor, 

rc 

re 

Restore cursor to position of last sc 

row_address, 

vpa 

cv 

Vertical position absolute (set row) (PG) 

save_cursor, 

sc 

sc 

Save cursor position (P) 

scrolLforward, 

ind 

sf 

Scroll text up (P) 

scrolLxeverse, 

ri 

sr 

Scroll text down (P) 

set_attributes, 

sgr 

sa 

Define the video attributes (PG9) 

set_tab, 

hts 

St 

Set a tab in all rows, current column 

set_window, 

wind 

wi 

Current window is lines #l-#2 cols #3-#4 

tab, 

ht 

ta 

Tab to next 8 space hardware tab stop 

to^statusjine, 

tsl 

ts 

Go to status line, column #1 

underline^char, 

uc 

uc 

Underscore one char and move past it 

upJhalLJine, 

hu 

hu 

Half-line up (reverse 1/2 linefeed) 

init_prog, 

iprog 

iP 

Path name of program for init 

key_al, 

kal 

Kl 

Upper left of keypad 

key_a3, 

ka3 

K3 

Upper right of keypad 

key 32, 

kb2 

K2 

Center of keypad 

key_cl, 

kcl 

K4 

Lower left of keypad 

key_c3, 

kc3 

K5 

Lower right of keypad 

prtr_non, 

mc5p 

pO 

Turn on the printer for #1 bytes 


A Sample Entry 

The following entry, which describes the Concept—100, is among the more complex 
entries in the termmfo file as of this writing. 


concept 1001 cl00| concept jcl04|c KXMpj concept 100, 

am, bel— A G, blank —\EH, blink—\EC, clear— A L$<2*>, cnorm—\Ew, 
cols#80, cr— A M$<9>, cubl- A H, cudl- A J, cufl-\E-, 
cup-\Ea%pl%’ *%+%c%p2%’ ’%+%c, 

cuul—\E;, cwis—\EW, db, dchl-\E A A$<16*>, dim-\EE, dll-\E A B$<3*>, 

ed—\E A C$<16*>, el—\E A U$<16>, eo, flash-\Ek$<20>\EK, ht-\t$<8> ; 

ill—\E A RS<3*>, in, ind— A J, .ind— A J$<9>, ip-$<16*>, 

is2—\EU\Ef\E7\E5\E8\EI\ENH\EK\E\200\Eo&\200\Eo\47\E, 

kbs— A h, kcubl—\E>, kcudl—\E<, kcufl-\E-, kcuul-\E„ 

kfl—\E5, kf2—\E6, kf3«\E7, khome-\E?, 

lines#24, mir, pb#9600, prot-\EI, rep-\Er%pl%c%p2%’ ’%+%c$<.2*>, 
rev-\ED, rmcup—\Ev $<6>\Ep\r\n, rmir—\E\200, rmkx-\Ex, 
rmso-\Ed\Ee, rmul-\Eg, rmul-\Eg, sgr0-\EN\200, 
smcup—\EU\Ev Bp\Ep\r, smir-\E A P, smkx—\EX ; smso«\EE\ED, 
smul-\EG, tabs, ul, vt#8, xenl, 
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Entries may continue onto multiple lines by placing white space at the beginning of 
each line except the first. Comments may be included on lines beginning with 
Capabilities in terminfo are of three types: Boolean capabilities which indicate that 
the terminal has some particular feature, numeric capabilities giving the size of the 
terminal or the size of particular delays, and string capabilities, which give a 
sequence which can be used to perform particular terminal operations. 

Types of Capabilities 

All capabilities have names. For instance, the fact that the Concept has automatic 
margins (i.e., an automatic return and linefeed when the end of a line is reached) is 
indicated by the capability am. Hence the description of the Concept includes am. 
Numeric capabilities are followed by the character and then the value. Thus 
cols, which indicates the number of columns the terminal has, gives the value ‘80’ for 
the Concept. 

Finally, string valued capabilities, such as el (clear to end of line sequence) are given 
by the two-character code, an and then a string ending at the next following *,’• 
A delay in milliseconds may appear anywhere in such a capability, enclosed in $<..> 
brackets, as in el=\EK$<3>, and padding characters are supplied by tputs to pro¬ 
vide this delay. The delay can be either a number, e.g., ‘20’, or a number followed 
by an V, i.e., ‘3*’. A V indicates that the padding required is proportional to the 
number of lines affected by the operation, and the amount given is the per-affected- 
unit padding required. (In the case of insert character, the factor is still the number 
of lines affected. This is always one unless the terminal has xenl and the software 
uses it.) When a V is specified, it is sometimes useful to give a delay of the form 
‘3.5’ to specify a delay per unit to tenths of milliseconds. (Only one decimal place is 
allowed.) 

A number of escape sequences are provided in the string valued capabilities for easy 
encoding of characters there. Both \E and \e map to an ESCAPE character, *x 
maps to a control-x for any appropriate x, and the sequences \n \1 \r \t \b \f \s 
give a newline, linefeed, return, tab, backspace, formfeed, and space. Other escapes 
include V f° r *> \\ for V V for comma, \: for :, and \0 for null. (\0 will produce 
\200, which does not terminate a string but behaves as a null character on most ter¬ 
minals.) Finally, characters may be given as three octal digits after a \. 

Sometimes individual capabilities must be commented out. To do this, put a period 
before the capability name. For example, see the second ind in the example above. 

Preparing Descriptions 

We now outline how to prepare descriptions of terminals. The most effective way to 
prepare a terminal description is by imitating the description of a similar terminal in 
terminfo and to build up a description gradually, using partial descriptions with vi to 
check that they are correct. Be aware that a very unusual terminal may expose 
deficiencies in the ability of the terminfo file to describe it or bugs in vi. To easily 
test a new terminal description you can set the environment variable TERMINFO to 
a pathname of a directory containing the compiled description you are working on 
and programs will look there rather than in fusrflibfterminfo. To get the padding 
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for insert line right (if the terminal manufacturer did not document it) a severe test 
is to edit /etc/passwd at 9600 baud, delete 16 or so lines from the middle of the 
screen, then hit the ‘u’ key several times quickly. If the terminal messes up, more 
padding is usually needed. A similar test can be used for insert character. 

Basic Capabilities 

The number of columns on each line for the terminal is given by the cob numeric 
capability. If the terminal is a CRT, then the number of lines on the screen is given 
by the lines capability. If the terminal wraps around to the beginning of the next 
line when it reaches the right margin, then it should have the am capability. If the 
terminal can clear its screen, leaving the cursor in the home position, then this is 
given by the clear string capability. If the terminal overstrikes (rather than clear¬ 
ing a position when a character is struck over) then it should have the os capability. 
If the terminal is a printing terminal, with no soft copy unit, give it both he and os. 
(os applies to storage scope terminals, such as TEKTRONIX 4010 series, as well as 
hard copy and APL terminals.) If there is a code to move the cursor to the left edge 
of the current row, give this as cr. (Normally this will be carriage return, control 
M.) If there is a code to produce an audible signal (bell, beep, etc) give this as bel. 

If there is a code to move the cursor one position to the left (such as backspace) that 
capability should be given as cubl. Similarly, codes to move to the right, up, and 
down should be given as cufl, cuul, and cudl. These local cursor motions should 
not alter the text they pass over, for example, you would not normally use ‘cufl= ’ 
because the space would erase the character moved over. 

A very important point here is that the local cursor motions encoded in terminfo are 
undefined at the left and top edges of a CRT terminal. Programs should never 
attempt to backspace around the left edge, unless bw is given, and never attempt to 
go up locally off the top. In order to scroll text up, a program will go to the bottom 
left corner of the screen and send the ind (index) string. 

To scroll text down, a program goes to the top left corner of the screen and sends 
the ri (reverse index) string. The strings ind and ri are undefined when not on their 
respective corners of the screen. 

Parameterized versions of the scrolling sequences are indn and rin which have the 
same semantics as ind and ri except that they take one parameter, and scroll that 
many lines. They are also undefined except at the appropriate edge of the screen. 


The am capability tells whether the cursor sticks at the right edge of the screen 
when text is output, but this does not necessarily apply to a cufl from the last 
column. The only local motion which is defined from the left edge is if bw is given, 
then a cubl from the left edge will move to the right edge of the previous row. If 
bw is not given, the effect is undefined. This is useful for drawing a box around the 
edge of the screen, for example. If the terminal has switch selectable automatic 
margins, the terminfo file usually assumes that this is on; i.e., am. If the terminal 
has a command which moves to the first column of the next line, that command can 
be given as nel (newline). It does not matter if the command clears the remainder of 
the current line, so if the terminal has no cr and If it may still be possible to craft a 
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working nel out of one or both of them. 

These capabilities suffice to describe hardcopy and “glass-tty” terminals. Thus the 
model 33 teletype is described as 

33 J tty33 [ tty J model 33 teletype, 

bel= A G, cols#72, cr= A M, cudl= A J, he, ind= A J, os, 

while the Lear Siegler ADM—3 is described as 

adm3 j 3 j lsi adm3, 

am, bel= A G, clear= A Z, cols#80, cr= A M, cubl= A H, cudl= A J, 
ind= A J, lines#24, 

Parameterized Strings 

Cursor addressing and other strings requiring parameters in the terminal are 
described by a parameterized string capability, with printj{ 3S) like escapes %x in it. 
For example, to address the cursor, the cup capability is given, using two parame¬ 
ters: the row and column to address to. (Rows and columns are numbered from zero 
and refer to the physical screen visible to the user, not to any unseen memory.) If 
the terminal has memory relative cursor addressing, that can be indicated by 
mrcup. 

The parameter mechanism uses a stack and special % codes to manipulate it. Typi¬ 
cally a sequence will push one of the parameters onto the stack and then print it in 
some format. Often more complex operations are necessary. 

The % encodings have the following meanings: 


%% outputs *%’ 

%d print pop() as in printf 

%2d print pop() like %2d 

%3d print pop() like %3d 

%02d 

%03d as in printf 

%c print pop() gives %c 

%s print pop() gives %s 

%p[l-9] push ith parm 

%P[a-z] set variable [a-z] to pop() 

%g[a-z] get variable [a-z] and push it 

%V char constant c 

%{nn} integer constant nn 

%+%-%*%/%m 

arithmetic (%m is mod): push(pop() op pop()) 
%& %\ % A bit operations: push(pop() op pop()) 

%= %> %< logical operations: push(pop() op pop()) 
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%\ %~ unary operations push(op pop()) 

%i add 1 to first two parms (for ANSI terminals) 

%! expr %t thenpart %t elsepart %; 

if-then-else, %e elsepart is optional, 
else-if’s are possible ala Algol 68: 

%t Cj %t b, %e Cg %t bg %e c,j %t bg %e %t b^ %e %; 
c- are conditions, b- are bodies. 

Binary operations are in postfix form with the operands in the usual order. That is, 
to get x-5 one would use "%gx%{5}%-". 

Consider the Hewlett-Packard 2645, which, to get to row 3 and column 12, needs to 
be sent \E&al2c03Y padded for 6 milliseconds. Note that the order of the rows and 
columns is inverted here, and that the row and column are printed as two digits. 
Thus its cup capability is “cup=6\E&%p2%2dc%pl%2dY”. 

The Microterm ACT-IV needs the current row and column sent preceded by a *T, 
with the row and column simply encoded in binary, “cup=*T%pl%c%p2%c”. Ter¬ 
minals which use “%c” need to be able to backspace the cursor (cubl), and to move 
the cursor up one line on the screen (cuul). This is necessary because it is not 
always safe to transmit \n *D and \r, as the system may change or discard them. 
(The library routines dealing with terminfo set tty modes so that tabs are never 
expanded, so \t is safe to send. This turns out to be essential for the Ann Arbor 
4080.) 

A final example is the LSI ADM-3a, which uses row and column offset by a blank 
character, thus “cup=\E=%pl%’ ’ %+%c%p2%’ , %+%c'\ After sending ‘\E=’, this 
pushes the first parameter, pushes the ASCII value for a space (32), adds them (push¬ 
ing the sum on the stack in place of the two previous values) and outputs that value 
as a character. Then the same is done for the second parameter. More complex 
arithmetic is possible using the stack. 

If the terminal has row or column absolute cursor addressing, these can be given as 
single parameter capabilities hpa (horizontal position absolute) and vpa (vertical 
position absolute). Sometimes these are shorter than the more general two parame¬ 
ter sequence (as with the hp2645) and can be used in preference to cup . If there are 
parameterized local motions (e.g., move n spaces to the right) these can be given as 
cud, cub, cuf, and cuu with a single parameter indicating how many spaces to 
move. These are primarily useful if the terminal does not have cup, such as the 
TEKTRONIX 4025. 

Cursor Motions 


If the terminal has a fast way to home the cursor (to very upper left corner of 
screen) then this can be given as home; similarly a fast way of getting to the lower 
left-hand corner can be given as 11; this may involve going up with cuul from the 
home position, but a program should never do this itself (unless 11 does) because it 
can make no assumption about the effect of moving up from the home position. 
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Note that the home position is the same as addressing to (0,0): to the top left corner 
of the screen, not of memory. (Thus, the \EH sequence on Hewlett-Packard termi¬ 
nals cannot be used for home.) 

Area Clears 

If the terminal can clear from the current position to the end of the line, leaving the 
cursor where it is, this should be given as el. If the terminal can clear from the 
current position to the end of the display, then this should be given as ed. Ed is 
only defined from the first column of a line. (Thus, it can be simulated by a request 
to delete a large number of lines, if a true ed is not available.) 

Insert/delete line 

If the terminal can open a new blank line before the line where the cursor is, this 
should be given as ill; this is done only from the first position of a line. The cursor 
must then appear on the newly blank line. If the terminal can delete the line which 
the cursor is on, then this should be given as dll; this is done only from the first 
position on the line to be deleted. Versions of ill and dll which take a single 
parameter and insert or delete that many lines can be given as il and dl. If the ter¬ 
minal has a settable scrolling region (like the vtlOO) the command to set this can be 
described with the csr capability, which takes two parameters: the top and bottom 
lines of the scrolling region. The cursor position is, alas, undefined after using this 
command. It is possible to get the effect of insert or delete line using this command 
— the sc and rc (save and restore cursor) commands are also useful. Inserting lines 
at the top or bottom of the screen can also be done using ri or ind on many termi¬ 
nals without a true insert/delete line, and is often faster even on terminals with 
those features. 

If the terminal has the ability to define a window as part of memory, which all com¬ 
mands affect, it should be given as the parameterized string wind. The four param¬ 
eters are the starting and ending lines in memory and the starting and ending 
columns in memory, in that order. 

If the terminal can retain display memory above, then the da capability should be 
given; if display memory can be retained below, then db should be given. These indi¬ 
cate that deleting a line or scrolling may bring non-blank lines up from below or that 
scrolling back with ri may bring down non-blank lines. 

Insert /Delete Character 

There are two basic kinds of intelligent terminals with respect to insert/delete char¬ 
acter which can be described using terminjo. The most common insert/delete 
character operations affect only the characters on the current line and shift charac¬ 
ters off the end of the line rigidly. Other terminals, such as the Concept 100 and the 
Perkin Elmer Owl, make a distinction between typed and untyped blanks on the 
screen, shifting upon an insert or delete only to an untyped blank on the screen 
which is either eliminated, or expanded to two untyped blanks. You can determine 
the kind of terminal you have by clearing the screen and then typing text separated 
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Note that the home position is the same as addressing to (0,0): to the top left corner 
of the screen, not of memory. (Thus, the \EH sequence on Hewlett-Packard termi¬ 
nals cannot be used for home.) 

Area Clears 

If the terminal can clear from the current position to the end of the line, leaving the 
cursor where it is, this should be given as el. If the terminal can clear from the 
current position to the end of the display, then this should be given as ed. Ed is 
only defined from the first column of a line. (Thus, it can be simulated by a request 
to delete a large number of lines, if a true ed is not available.) 

Insert/delete line 

If the terminal can open a new blank line before the line where the cursor is, this 
should be given as ill; this is done only from the first position of a line. The cursor 
must then appear on the newly blank line. If the terminal can delete the line which 
the cursor is on, then this should be given as dll; this is done only from the first 
position on the line to be deleted. Versions of ill and dll which take a single 
parameter and insert or delete that many lines can be given as il and dl. If the ter¬ 
minal has a settable scrolling region (like the vtlOO) the command to set this can be 
described with the csr capability, which takes two parameters: the top and bottom 
lines of the scrolling region. The cursor position is, alas, undefined after using this 
command. It is possible to get the effect of insert or delete line using this command 
— the sc and re (save and restore cursor) commands are also useful. Inserting lines 
at the top or bottom of the screen can also be done using ri or ind on many termi¬ 
nals without a true insert/delete line, and is often faster even on terminals with 
those features. 


If the terminal has the ability to define a window as part of memory, which all com¬ 
mands affect, it should be given as the parameterized string wind. The four param¬ 
eters are the starting and ending lines in memory and the starting and ending 
columns in memory, in that order. 

If the terminal can retain display memory above, then the da capability should be 
given; if display memory can be retained below, then db should be given. These indi¬ 
cate that deleting a line or scrolling may bring non-blank lines up from below or that 
scrolling back with ri may bring down non-blank lines. 

Insert /Delete Character 

There are two basic kinds of intelligent terminals with respect to insert/delete char¬ 
acter which can be described using terminfo. The most common insert/delete 
character operations affect only the characters on the current line and shift charac¬ 
ters off the end of the line rigidly. Other terminals, such as the Concept 100 and the 
Perkin Elmer Owl, make a distinction between typed and untyped blanks on the 
screen, shifting upon an insert or delete only to an untyped blank on the screen 
which is either eliminated, or expanded to two untyped blanks. You can determine 
the kind of terminal you have by clearing the screen and then typing text separated 
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by cursor motions. Type “abc def” using local cursor motions (not spaces) 
between the “abc” and the “def”. Then position the cursor before the “abc” and put 
the terminal in insert mode. If typing characters causes the rest of the line to shift 
rigidly and characters to fall off the end, then your terminal does not distinguish 
between blanks and untyped positions. If the “abc” shifts over to the “def” which 
then move together around the end of the current line and onto the next as you 
insert, you have the second type of terminal, and should give the capability in, which 
stands for “insert null”. While these are two logically separate attributes (one line 
vs. multiline insert mode, and special treatment of untyped spaces) we have seen no 
terminals whose insert mode cannot be described with the single attribute. 

Terminfo can describe both terminals which have an insert mode, and terminals 
which send a simple sequence to open a blank position on the current line. Give as 
smir the sequence to get into insert mode. Give as rmir the sequence to leave 
insert mode. Now give as ichl any sequence needed to be sent just before sending 
the character to be inserted. Most terminals with a true insert mode will not give 
ichl; terminals which send a sequence to open a screen position should give it here. 
(If your terminal has both, insert mode is usually preferable to ichl. Do not give 
both unless the terminal actually requires both to be used in combination.) If post 
insert padding is needed, give this as a number of milliseconds in ip (a string option). 
Any other sequence which may need to be sent after an insert of a single character 
may also be given in ip. If your terminal needs both to be placed into an ‘insert 
mode’ and a special code to precede each inserted character, then both smir /rmir 
and ichl can be given, and both will be used. The ich capability, with one parame¬ 
ter, n, will repeat the effects of ichl n times. 

It is occasionally necessary to move around while in insert mode to delete characters 
on the same line (e.g., if there is a tab after the insertion position). If your terminal 
allows motion while in insert mode you can give the capability mir to speed up 
inserting in this case. Omitting mir will affect only speed. Some terminals (notably 
Datamedia’s) must not have mir because of the way their insert mode works. 

Finally, you can specify dchl to delete a single character, dch with one parameter, 
n, to delete n characters, and delete mode by giving smdc and rmdc to enter and 
exit delete mode (any mode the terminal needs to be placed in for dchl to work). 

A command to erase n characters (equivalent to outputting n blanks without moving 
the cursor) can be given as ech with one parameter. 

Highlighting, Underlining, and Visible Bells 

If your terminal has one or more kinds of display attributes, these can be 
represented in a number of different ways. You should choose one display form as 
standout mode, representing a good, high contrast, easy-on-the-eyes, format for 
highlighting error messages and other attention getters. (If you have a choice, 
reverse video plus half-bright is good, or reverse video alone.) The sequences to enter 
and exit standout mode are given as smso and rmso, respectively. If the code to 
change into or out of standout mode leaves one or even two blank spaces on the 
screen, as the TVI 912 and Teleray 1061 do, then xmc should be given to tell how 
many spaces are left. 
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Codes to begin underlining and end underlining can be given as smul and rmul 
respectively. If the terminal has a code to underline the current character and move 
the cursor one space to the right, such as the Microterm Mime, this can be given as 

uc. 


Other capabilities to enter various highlighting modes include blink (blinking) bold 
(bold or extra bright) dim (dim or half-bright) invis (blanking or invisible text) prot 
(protected) rev (reverse video) sgrO (turn off all attribute modes) smacs (enter 
alternate character set mode) and rmacs (exit alternate character set mode). Turn¬ 
ing on any of these modes singly may or may not turn off other modes. 

If there is a sequence to set arbitrary combinations of modes, this should be given as 
sgr (set attributes), taking 9 parameters. Each parameter is either 0 or 1, as the 
corresponding attribute is on or off. The 9 parameters are, in order: standout, 
underline, reverse, blink, dim, bold, blank, protect, alternate character set. Not all 
modes need be supported by sgr, only those for which corresponding separate attri¬ 
bute commands exist. 

Terminals with the “magic cookie” glitch (xmc) deposit special “cookies” when they 
receive mode-setting sequences, which affect the display algorithm rather than hav¬ 
ing extra bits for each character. Some terminals, such as the Hewlett-Packard 
2621, automatically leave standout mode when they move to a new line or the cursor 
is addressed. Programs using standout mode should exit standout mode before mov¬ 
ing the cursor or sending a newline, unless the msgr capability, asserting that it is 
safe to move in standout mode, is present. 

If the terminal has a way of flashing the screen to indicate an error quietly (a bell 
replacement) then this can be given as flash; it must not move the cursor. 

If the cursor needs to be made more visible than normal when it is not on the bot¬ 
tom line (to make, for example, a non-blinking underline into an easier to find block 
or blinking underline) give this sequence as cvvis. If there is a way to make the cur¬ 
sor completely invisible, give that as civis. The capability cnorm should be given 
which undoes the effects of both of these modes. 

If the terminal needs to be in a special mode when running a program that uses 
these capabilities, the codes to enter and exit this mode can be given as smcup and 
rmcup. This arises, for example, from terminals like the Concept with more than 
one page of memory. If the terminal has only memory relative cursor addressing and 
not screen relative cursor addressing, a one screen-sized window must be fixed into 
the terminal for cursor addressing to work properly. This is also used for the TEK¬ 
TRONIX 4025, where smcup sets the command character to be the one used by ter- 
minfo. 


If your terminal correctly generates underlined characters (w'ith no special codes 
needed) even though it does not overstrike, then you should give the capability ul. If 
overstrikes are erasable with a blank, then this should be indicated by giving eo. 


12 


Icon International, Inc. 



TERMINFO (4) 


FILE FORMATS 


TERMINFO (4) 


Keypad 

If the terminal has a keypad that transmits codes when the keys are pressed, this 
information can be given. Note that it is not possible to handle terminals where the 
keypad only works in local (this applies, for example, to the unshifted Hewlett- 
Packard 2621 keys). If the keypad can be set to transmit or not transmit, give these 
codes as smkx and rmkx. Otherwise the keypad is assumed to always transmit. 
The codes sent by the left arrow, right arrow, up arrow, down arrow, and home keys 
can be given as kcubl, kcufl, kcuul, kcudl, and khome respectively. If there 
are function keys such as fO, fl, ..., flO, the codes they send can be given as kfD, kfl, 
kflO. If these keys have labels other than the default fO through flO, the labels 
can be given as IfO, lfl, lflO. The codes transmitted by certain other special 
keys can be given: kll (home down), kbs (backspace), ktbc (clear all tabs), kctab 
(clear the tab stop in this column), kclr (clear screen or erase key), kdchl (delete 
character), kdll (delete line), krmir (exit insert mode), kel (clear to end of line), 
ked (clear to end of screen), kichl (insert character or enter insert mode), kill 
(insert line), knp (next page), kpp (previous page), kind (scroll forward/down), kri 
(scroll backward/up), khts (set a tab stop in this column). In addition, if the 
keypad has a 3 by 3 array of keys including the four arrow keys, the other five keys 
can be given as kal, ka3, kb2, kcl, and kc3. These keys are useful when the 
effects of a 3 by 3 directional pad are needed. 

Tabs and Initialization 

If the terminal has hardware tabs, the command to advance to the next tab stop 
can be given as ht (usually control I). A “backtab” command which moves leftward 
to the next tab stop can be given as cbt. By convention, if the teletype modes indi¬ 
cate that tabs are being expanded by the computer rather than being sent to the 
terminal, programs should not use ht or cbt even if they are present, since the user 
may not have the tab stops properly set. If the terminal has hardware tabs which 
are initially set every n spaces when the terminal is powered up, the numeric param¬ 
eter it is given, showing the number of spaces the tabs are set to. This is normally 
used by the tset command to determine whether to set the mode for hardware tab 
expansion, and whether to set the tab stops. If the terminal has tab stops that can 
be saved in nonvolatile memory, the terminfo description can assume that they are 
properly set. 

Other capabilities include isl, is2, and is3, initialization strings for the terminal, 
iprog, the path name of a program to be run to initialize the terminal, and if, the 
name of a file containing long initialization strings. These strings are expected to set 
the terminal into modes consistent with the rest of the terminfo description. They 
are normally sent to the terminal, by the tset program, each time the user logs in. 
They will be printed in the following order: isl; is2; setting tabs using tbc and hts; 
if; running the program iprog; and finally is3. Most initialization is done with is2. 
Special terminal modes can be set up without duplicating strings by putting the 
common sequences in is2 and special cases in isl and is3. A pair of sequences that 
does a harder reset from a totally unknown state can be analogously given as rsl, 
rs2, rf, and rs3, analogous to is2 and if. These strings are output by the reset pro¬ 
gram, which is used when the terminal gets into a wedged state. Commands are 
normally placed in rs2 and rf only if they produce annoying effects on the screen and 
are not necessary when logging in. For example, the command to set the vtlOO into 
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80-column mode would normally be part of is2, but it causes an annoying glitch of 
the screen and is not normally needed since the terminal is usually already in 80 
column mode. 

If there are commands to set and clear tab stops, they can be given as tbc (clear all 
tab stops) and hts (set a tab stop in the current column of every row). If a more 
complex sequence is needed to set the tabs than can be described by this, the 
sequence can be placed in is2 or if. 

Delays 

Certain capabilities control padding in the teletype driver. These are primarily 
needed by hard copy terminals, and are used by the tset program to set teletype 
modes appropriately. Delays embedded in the capabilities cr, ind, cubl, ff, and tab 
will cause the appropriate delay bits to be set in the teletype driver. If pb (padding 
baud rate) is given, these values can be ignored at baud rates below the value of pb. 

Miscellaneous 


If the terminal requires other than a null (zero) character as a pad, then this can be 
given as pad. Only the first character of the pad string is used. 

If the terminal has an extra “status line” that is not normally used by software, this 
fact can be indicated. If the status line is viewed as an extra line below the bottom 
line, into which one can cursor address normally (such as the Heathkit hl9’s 25th 
line, or the 24th line of a vtlOO which is set to a 23-line scrolling region), the capabil¬ 
ity hs should be given. Special strings to go to the beginning of the status line and 
to return from the status line can be given as tsl and fsl. (fsl must leave the cursor 
position in the same place it was before tsl. If necessary, the sc and re strings can 
be included in tsl and fsl to get this effect.) The parameter tsl takes one parameter, 
which is the column number of the status line the cursor is to be moved to. If escape 
sequences and other special commands, such as tab, work while in the status line, the 
flag eslok can be given. A string which turns off the status line (or otherwise erases 
its contents) should be given as dsl. If the terminal has commands to save and 
restore the position of the cursor, give them as sc and rc. The status line is nor¬ 
mally assumed to be the same width as the rest of the screen, e.g., cols. If the 
status line is a different width (possibly because the terminal does not allow an 
entire line to be loaded) the width, in columns, can be indicated with the numeric 
parameter wsl. 

If the terminal can move up or down half a line, this can be indicated with hu (half¬ 
line up) and hd (half-line down). This is primarily useful for superscripts and sub¬ 
scripts on hardcopy terminals. If a hardcopy terminal can eject to the next page 
(form feed), give this as flf (usually control L). 

If there is a command to repeat a given character a given number of times (to save 
time transmitting a large number of identical characters) this can be indicated with 
the parameterized string rep. The first parameter is the character to be repeated 
and the second is the number of times to repeat it. Thus, t.parm(repeat_char, ’x\ 10) 
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is the same as ‘xxxxxxxxxx’. 

If the terminal has a settable command character, such as the TEKTRONIX 4025, 
this can be indicated with emdch. A prototype command character is chosen which 
is used in all capabilities. This character is given in the cmdch capability to iden¬ 
tify it. The following convention is supported on some UNIX systems: The environ¬ 
ment is to be searched for a CC variable, and if found, all occurrences of the proto¬ 
type character are replaced with the character in the environment variable. 

Terminal descriptions that do not represent a specific kind of known terminal, such 
as switch, dialup, patch, and network, should include the gn (generic) capability so 
that programs can complain that they do not know how to talk to the terminal. 
(This capability does not apply to virtual terminal descriptions for which the escape 
sequences are known.) 

If the terminal uses xon/xoff handshaking for flow control, give xon. Padding infor¬ 
mation should still be included so that routines can make better decisions about 
costs, but actual pad characters will not be transmitted. 

If the terminal has a “meta key” which acts as a shift key, setting the 8th bit of any 
character transmitted, this fact can be indicated with km. Otherwise, software will 
assume that the 8th bit is parity and it will usually be cleared. If strings exist to 
turn this “meta mode” on and off, they can be given as smm and rmm. 

If the terminal has more lines of memory than will fit on the screen at once, the 
number of lines of memory can be indicated with lm. A value of lm#0 indicates 
that the number of lines is not fixed, but that there is still more memory than fits on 
the screen. 

If the terminal is one of those supported by the UNIX system virtual terminal proto¬ 
col, the terminal number can be given as vt. 

Media copy strings which control an auxiliary printer connected to the terminal can 
be given as mcO: print the contents of the screen, mc4: turn off the printer, and 
mc5: turn on the printer. When the printer is on, all text sent to the terminal will 
be sent to the printer. It is undefined whether the text is also displayed on the ter¬ 
minal screen when the printer is on. A variation mc5p takes one parameter, and 
leaves the printer on for as many characters as the value of the parameter, then 
turns the printer off. The parameter should not exceed 255. All text, including mc4, 
is transparently passed to the printer while an mc5p is in effect. 


Strings to program function keys can be given as pfkey, pfloc, and pfx. Each of 
these strings takes two parameters: the function key number to program (from 0 to 
10) and the string to program it with. Function key numbers out of this range may 
program undefined keys in a terminal dependent manner. The difference between the 
capabilities is that pfkey causes pressing the given key to be the same as the user 
typing the given string; pfloc causes the string to be executed by the terminal in 
local; and pfx causes the string to be transmitted to the computer. 
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Glitches and Braind&m&ge 

Hazeltine terminals, which do not allow characters to be displayed should indi¬ 
cate hz. 

Terminals which ignore a linefeed immediately after an am wrap, such as the Con¬ 
cept and vtlOO, should indicate xenl. 

If el is required to get rid of standout (instead of merely writing normal text on top 
of it), xhp should be given. 

Teleray terminals, w'here tabs turn all characters moved over to blanks, should indi¬ 
cate xt (destructive tabs). This glitch is also taken to mean that it is not possible to 
position the cursor on top of a “magic cookie”, that to erase standout mode it is 
instead necessary to use delete and insert line. 

The Beehive Superbee, which is unable to correctly transmit the escape or control C 
characters, has xsb, indicating that the fl key is used for escape and f2 for control 
C. (Only certain Superbees have this problem, depending on the ROM.) 

Other specific terminal problems may be corrected by adding more capabilities of 
the form xx. 

Similar Terminals 


If there are two very similar terminals, one can be defined as being just like the 
other with certain exceptions. The string capability use can be given with the name 
of the similar terminal. The capabilities given before use override those in the ter¬ 
minal type invoked by use. A capability can be cancelled by placing xx@ to the left 
of the capability definition, where xx is the capability. For example, the entry 

2621-nl, smkx@, rmkx@, use =2621, 

defines a 2621-nl that does not have the smkx or rmkx capabilities, and hence does 
not turn on the function key labels when in visual mode. This is useful for different 
modes for a terminal, or for different user preferences. 


FILES 


/usr/lib/terminfo/?/* files containing terminal descriptions 


SEE ALSO 

curses(3X), printf(3S), term(5). 

tic(lM) in the ICON/UXV Administrator Reference Manual. 
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NAME 

utmp, wtmp — utmp and wtmp entry formats 


SYNOPSIS 

#inelude <sys/types.h> 
^include <utmp.h> 


DESCRIPTION 


These files, which hold user and accounting information for such commands as 
who(l), write{ 1), and login{ 1), have the following structure as defined by <utmp.h>: 


#define UTMP_FILE "/etc/utmp" 

#define WTMP_FILE "/etc/wtmp" 

^define ut_name ut_user 


struct 


}; 


utmp { 
char 

ut_user 

[8]; 

j 

/* User login name */ 

char 

ut_id[4 

/* /etc/inittab id (usually line #) */ 

char 

utjine 

[12]; 

/* device name (console, lnxx) */ 

short 

ut_pid; 


/* process id */ 

short 

ut_type; 

/* type of entry */ 

struct 

exit_statiis { 


short 

extermination; 

/* Process termination status */ 

short 

e_exit; 

/* Process exit status */ 

} ut_exit; 



/* The exit status of a process 
* marked as DEAD_PROCESS. */ 

time_t 

ut_time; 

/* time entry was made */ 


/* Definitions for ut_type */ 


#define EMPTY 0 

#define RUN_LVL 1 

#define BOOT.TIME 2 

#define OLD.TIME 3 

#define NEW.TIME 4 
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#define IN1T_PR0CESS 
#defme LOGIN_PROCESS 
#define USER_PROCESS 
#define DE1AD_PR0CESS 
#define ACCOUNTING 
#define UTMAXTYPE 


5 /* Process spawned by "init" */ 

6 /* A "getty” process waiting for login */ 

7 /* A user process */ 

8 
9 

ACCOUNTING /* Largest legal value of ut_type */ 


/* Special strings or formats used in the "utjine" field when */ 
/* accounting for something other than a process */ 

/* No string for the utjine field can be more than 11 chars + */ 
/* a NULL in length */ 

#define RUNLVL_MSG "run-level %c" 

^define BOOT_MSG "system boot" 

#define OTIMELMSG "old time" 

#define NT1ME_MSG "new time" 


FILES 

/usr/include/utmp.h 

/etc/utmp 

/etc/wtmp 


SEE ALSO 

getut(3C). 

login(l), who(l), write(l) in the ICON/UXV User Reference Manual. 
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NAME 

uxrc — ICON/UXB run-time configuration file 


SYNOPSIS 

/etc/uxrc 


DESCRIPTION 

Uxrc is used to set configuration variables in the operating system kernel. When a 
reboot is in progress, / etc/uxrc is read to optionally set the value of certain kernel 
variables. 

The general form of a line in uxrc is: 


variable-name hexadecimal-value 


where variable-name is one of the variables defined below, and hexadecimal-value is a 
hexadecimal representation of the value to be assigned to that variable. Currently, 
there are eight variables defined that may be set in uxrc. They are: 


mot_mode 

pcp_modex 

anet_ml_pcpO 

dcsx_config 

dcsxy_cctype 

dcsxj/_modem 

dcsxj/_handshake 

autoboot 


Main CPU board serial port control. 
PCP board x serial port control. 
Z-NET control for PCP board 0 ports. 
DCS adapter x cluster config. 

DCS adapter x cluster y config. 

DCS adapter x cluster y config. 

DCS adapter x cluster y config. 
Auto-boot on panic flag. 


Other variables will be made available in uxrc as the need arises. 


MOT_MODE 

Hardware handshake and modem control behavior for the Main CPU serial commun¬ 
ication ports may be modified by changing the mot_mode variable. The lower 4 
bits enable hardware RTS/CTS handshaking and the upper 4 bits enable modem 
control. 

Control: Hardware Handshaking (bits 0-3) 

Modem Control (bits 4-7) 

Bit: 7 6 5 4 3 2 1 0 

Port: 03 02 01 00 03 02 01 00 
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For example, to enable RTS/CTS handshaking on Port 01 and modem control on 
Port 02 the following line should be added to fetc/uxrc. 


mot_mode 42 


PCP_MODE:r 

Hardware handshake and modem control behavior for PCP16 serial communication 
ports may be modified by changing the pcp_modex variables, where x is the PCP 
board number. The lower 16 bits enable hardware RTS/CTS handshaking and the 
upper 16 bits enable modem control. 


Control: 

Bit: 

31 

30 

Modem Control 
29 28 27 

26 

25 

24 

Port: 

Of 

Oe 

Od 0c 0b 

0a 

09 

08 

Control: 

Bit: 

23 

22 

Modem Control 
21 20 19 

18 

17 

16 

Port: 

07 

06 

05 04 03 

02 

01 

00 

Control: 

Bit: 

15 

Hardware Handshaking 

14 13 12 11 10 

9 

8 

Port: 

Of 

0e 

Od 0c 0b 

0a 

09 

08 

Control: 

Bit: 

7 

Hardware Handshaking 

6 5 4 3 2 

1 

0 

Port: 

07 

06 

05 04 03 

02 

01 

00 


For example, to enable RTS/CTS handshaking on Port 09 and modem control on 
Port Oe on PCPO, the following line should be added to /etc/uxrc. 


pcp_mode0 40000200 


ZNET_M1JPCP0 

Currently, the only ports which may be configured as Z-NET ports are the serial 
ports on PCPO. Z-NET ports must be configured in pairs for the operating system to 
handle the ports correctly. The ports are groups in pairs as follows: (00, 01), (02, 03), 
(04, 05), . . . (Oe, Of). 

If one or more ports on PCPO are configured as Z-NET ports, the remaining ports 
will not work reliably at high data-input rates. 


2 


Icon International, Inc. 



UXRC(4) 


FILE FORMATS 


UXRC(4) 


Pairs of ports are configured to run Z-NET by setting the appropriate bits in the 
znet_ml_pcpO variable in uxrc. When the appropriate bit is on, then the port is 
configured as a Z-NET port. 

Control: Z-NET Select 


Bit: 

15 

14 

13 12 11 

10 

9 

8 

Port: 

Of 

Oe 

Od 0c Ob 

0a 

09 

08 

Control: 

Bit: 

7 

6 

Z-NET Select 

5 4 3 

2 

1 

0 

Port: 

07 

06 

05 04 03 

02 

01 

00 


For example, to configure ports aO, al, a4, a5, ae, and af as Z-NET ports, add the 
following line to the uxrc file: 


znet_ml_pcpO c033 


Once a port is configured as a Z-NET port, the baud rate is set to 38.4kbaud and 
any baud rate settings in the /etc/ttys file for that port are ignored. Make sure that 
port is configured as a login port in the /etc/ttys file, and that the associated entry 
in / etc/ttytype shows the correct terminal type (which will vary depending upon the 
terminal emulation program being used on the PC attached to the port). 


DCS*_CONFIG 

By default, the Distributed Communications Subsystem (DCS) driver allows the con¬ 
nection of any combination of DCS8, DCS9 and DCS16 cluster controllers with a 
maximum of 64 total ports. There are 128 minor devices addressable in all; the dev¬ 
ices that are active depends on the configuration. 

The uxrc variable dcsx_config specifies the basic default configuration for a DCS 
host adapter, where x is the DCS host adapter number. If this variable is set to 0, 
or is not present in uxrc, DCS will allow any combination of DCS8, DCS9, and 
DCS 16 cluster controllers, at all cluster addresses from 1 to f. 

If the variable is set to 1, only DCS8 and DCS9 clusters may be used, with cluster 
addresses 1 through 8 reserved for DCS8 clusters, and 8 through f reserved for DCS9 
clusters. This mode of configuration is intended to support older DCS cluster con¬ 
troller firmware. 

DCS:ry_CCTYPE 

The uxrc variable dcsxy_cctype allows you to override the default configuration on 
a cluster-by-cluster basis, in either setting of the dcsx_config variable. Again, x is 
the DCS host adapter number, and y is the cluster controller address. Using this 
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UXRC(4) 


variable is necessary only with older cluster controllers. To configure a cluster con¬ 
troller as a DCS8, use the value 8; use the value 9 for a DCS9, and the value 16 for a 
DCS16. 


DCSxjlJMODEM 

Modem control behavior for serial ports on DCS adapter x cluster controller y may 
be modified by changing the dcsxt/_roodem variables. When the appropriate bit is 
set, modem control is enabled; when the bit is clear, it is disabled. 

For each port on which modem support in enabled, a second minor device for the 
port becomes usable. For a discussion of the additional features and advantages of 
the additional device entry, see dcs(4). 


Control: 

Bit: 

15 

14 

Modem Control 
13 12 11 

10 

9 

8 

Port: 

Of 

Oe 

Od 0c Ob 

0a 

09 

08 

Control: 

Bit: 

7 

6 

Modem Control 

5 4 3 

2 

1 

0 

Port: 

07 

06 . 

05 04 03 

02 

01 

00 


DCSxy_HANDSHAKE 

Hardware handshaking behavior for serial ports on DCS adapter x cluster controller 
y may be modified by changing the dcsxy_handshake variables. When the 
appropriate bit is set, RTS/CTS handshaking is enabled; when the bit is clear, it is 
disabled. 


Control: 

Bit: 

15 

Hardware Handshaking 

14 13 12 11 10 

9 

8 

Port: 

Of 

Oe Od 0c 0b 0a 

09 

08 

Control: 

Bit: 

7 

Hardware Handshaking 

6 5 4 3 2 

1 

0 

Port: 

07 

06 05 04 03 02 

01 

00 


AUTOBOOT 


To force the machine to reboot automatically on a panic, autoboot must be set. 
When the system reboots, the panic message is scrolled off of the system console ter¬ 
minal display screen and is therefore lost, as the operating system cannot save the 
panic message. To enable this feature, the following line should be added to 
/ etc/uxrc. 
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autoboot 1 


BUGS 


For ports on a PCP, both RTS/CTS handshaking and modem control may not be 
enabled at the same time on the same port. 


SEE ALSO 

tty(7), dcs(7), terminfo(7) 

See the ICON/UXV Administrator Reference Manual, for a description of how to 
make cables for use with RTS/CTS hardware handshaking and modem control. 
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INTRO (5) 


NAME 

intro — introduction to miscellany 


DESCRIPTION 

This section describes miscellaneous facilities such as macro packages, character set 
tables, etc. 
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ASCII(5) 


NAME 

ascii — map of ASCII character set 


SYNOPSIS 

cat /usr/pub/ascii 


DESCRIPTION 

Ascii is a map of the ASCII character set, giving both octal and hexadecimal 
equivalents of each character, to be printed as needed. It contains: 


000 

nul 

! ooi 

soh 

J002 

s tx 

[003 

etx 

[004 

eot 

[005 

enq 

[006 

ack 

010 

bs 

•oil 

ht 

J012 

nl 

[013 

vt 

[014 

np 

[015 

c r 

[016 

so 

020 

die 

•021 

del 

J022 

dc2 

[023 

dc3 

[024 

dc4 

[025 

nak 

[026 

syn 

030 

can 

•031 

em 

•032 

sub 

[033 

esc 

[034 

f s 

[035 

gs 

[036 

r s 

040 

sp 

‘041 

f 

j 042 

*» 

[043 

# 

[044 

$ 

[045 

% 

[046 

& 

050 

( 

1051 

) 

•052 

* 

[053 

+ 

[054 

t 

[055 

— 

[056 

, 

060 

0 

[061 

1 

J 062 

2 

[063 

3 

[064 

4 

[065 

5 

[066 

6 

070 

8 

‘071 

9 

[072 


[073 


[074 

< 

[075 

= 

[076 

> 

100 

@ 

{101 

A 

[102 

B 

[ 103 

c 

[104 

D 

[105 

E 

[106 

F 

110 

H 

Jill 

I 

[112 

J 

[113 

K 

[114 

L 

[115 

M 

[116 

N 

120 

P 

,'121 

Q 

[122 

R 

[123 

S 

] 124 

T 

[125 

U 

[126 

V 

130 

X 

1131 

Y 

[132 

Z 

[133 

[ 

[134 

\ 

[135 

] 

[136 

* 

140 


J 141 

a 

[142 

b 

[143 

c 

[144 

d 

[145 

e 

[146 

f 

150 

h 

1151 

i 

[152 

j 

[ 153 

k 

[154 

1 

[155 

m 

[156 

n 

160 

P 

J161 

q 

[162 

r 

[163 

s 

[164 

t. 

[ 165 

u 

[166 

V 

170 

X 

',171 

y 

[172 

z 

[173 

{ 

[174 

1 

1 

[175 

> 

[176 


00 

nul 

| 01 

soh 

[ 02 

stx 

[ 03 

etx 

,' 04 

eot 

j 05 

enq 

[ 06 

ack 

08 

bs 

| 09 

ht 

[ 0a 

nl 

[ 0b 

vt 

[ 0c 

np 

[ Od 

cr 

[ Oe 

so 

10 

die 

i H 

dc 1 

[ 12 

dc2 

[ 13 

dc3 

[ 14 

dc4 

j 15 

nak 

[ 16 

syn 

18 

can 

! 1 9 

em 

[ la 

sub 

[ lb 

esc 

! 1c 

fs 

[ Id 

gs 

1 le 

r s 

20 

sp 

i 21 

| 

[ 22 

«• 

[ 23 

# 

[ 24 

$ 

[ 25 

% 

[ 26 

& 

28 

( 

J 29 

i 

[ 2a 

* 

[ 2b 

+ 

! 2c 

y 

[ 2d 

— 

[ 2e 

. 

30 

0 

j 31 

1 

[ 32 

2 

[ 33 

3 

[ 34 

4 

[ 35 

5 

[ 36 

6 

38 

8 

| 39 

9 

[ 3a 


[ 3b 

> 

[ 3c 

< 

[ 3d 

= 

[ 3e 

> 

40 

@ 

! 41 

A 

[ 42 

B 

[ 43 

c 

[ 44 

D 

[ 45 

E 

[ 46 

F 

48 

H 

J 49 

I 

[ 4a 

J 

[ 4b 

K 

[ 4c 

L 

[ 4d 

M 

[ 4e 

N 

50 

P 

! 5i 

Q 

j 52 

R 

[ 53 

S 

[ 54 

T 

j 55 

U 

| 56 

V 

58 

X 

J 59 

Y 

[ 5a 

Z 

[ 5b 

[ 

[ 5c 

\ 

[ 5d 

] 

[ 5e 

* 

60 


J 61 

a 

[ 62 

b 

[ 63 

c 

[ 64 

d 

[ 65 

e 

[ 66 

f 

68 

h 

j 69 

i 

[ 6a 

j 

[ 6b 

k 

[ 6c 

1 

[ 6d 

m 

[ 6e 

n 

70 

P 

j 71 

q 

[ 72 

r 

[ 73 

s 

[ 74 

t 

i 75 

u 

J 76 

V 

78 

X 

! 79 

y 

[ 7a 

z 

! 7b 

{ 

! 7c 

1 

1 

[ 7d 

} 

[ 7 e 
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FILES 



/usr/pub/ascii 
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ENVIRON (5) MISCELLANEOUS ENVIRON(5) 

NAME 

environ — user environment 


DESCRIPTION 

An array of strings called the “environment” is made available by e:rec(2) when a 
process begins. By convention, these strings have the form “name=value”. The fol¬ 
lowing names are used by various commands: 

PATH The sequence of directory prefixes that «/»(l), time(l), m'ce(l), nohup( 1), etc., 
apply in searching for a file known by an incomplete path name. The prefixes 
are separated by colons (:). Login{ 1) sets PATH=:/bin:/usr/bm. 

HOME Name of the user’s login directory, set by login( 1) from the password file 
passwd(4). 

TERM The kind of terminal for which output is to be prepared. This information is 
used by commands, such as mm( 1) or tplot( 1G), which may exploit special 
capabilities of that terminal. 

TZ Time zone information. The format is xxxnzzz where xxx is standard local 
time zone abbreviation, n is the difference in hours from GMT, and zzz is the 
abbreviation for the daylight-saving local time zone, if any; for example, 

EST5EDT. 

Further names may be placed in the environment by the export command and 
“name=value” arguments in s/j( 1), or by ezec(2). It is unwise to conflict with certain 
shell variables that are frequently exported by .profile files: MAIL, PSi, PS2, IFS. 


SEE ALSO 

exec(2). 

env(l), login(l), sh(l), mm(l), nice(l), nohup(l), time(l), tplot(lG) in the ICON/UXV 
User Reference Manual. 
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NAME 

fcntl — file control options 


SYNOPSIS 

^include <fcntl.h> 


DESCRIPTION 

The fcntl( 2) function provides for control over open files. The include file describes 
requests and arguments to fcntl and open( 2). 

/* Flag values accessible to open(2) and fcntl(2) */ 

/* (The first three can only be set by open) */ 

#define OJFtDONLY 0 

#define O.WRONLY 1 

#define O.RDWR 2 

#define O^NDELAY 04 /* Non-blocking I/O */ 

#define O.APPEND 010 /* append (writes guaranteed at the end) */ 

/* Flag values accessible only to open(2) */ 

#define 0_CREAT 00400 /* open with file create (uses third open arg) */ 

#define OJTRUNC 01000 /* open with truncation */ 

#define O^EXCL 02000 /* exclusive open */ 

/* fcntl(2) requests */ 

#define FJDUPFD 0 /* Duplicate fildes */ 

#define F_GETFD 1 /* Get fildes flags */ 

#define FJ5ETFD 2 /* Set fildes flags */ 

#define F..GETFL 3 /* Get file flags */ 

#define FJSETFL 4 /* Set file flags */ 

#define F_GETLK 5 /* Get blocking file locks */ 

#define FJ5ETLK 6 /* Set or clear file locks and fail on busy */ 

#define FJSETLKW 7 /*Set or clear file locks and wait on busy */ 

/* file segment locking control structure */ 
struct flock 

short Ltype; 

short l_whence; 

long l_jstart; 

long Uen; /* if 0 then until EOF *[ 

int Lpid; /* returned with F_GETLK */ 

/* file segment locking types */ 

^define F_RDLCK 01 /* Read lock */ 

pefine F.WRLCK 02 /* Write lock */ 

^define F_UNLCI< 03 /* Remove locks */ 


SEE ALSO 

fcntl(2), open(2). 
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NAME 

math — math functions and constants 


SYNOPSIS 

^include <math.h> 


DESCRIPTION 

This file contains declarations of all the functions in the Math Library (described in 
Section 3M), as well as various functions in the C Library (Section 3C) that return 
floating-point values. It defines the structure and constants used by the matherr(3M) 
error-handling mechanisms, including the following constant used as an error-return 


value: 


HUGE 

The maximum value of a single-precision floating-point 
number. The following mathematical constants are defined 
for user convenience: 

M_E 

The base of natural logarithms (e). 

M-LOG2E 

The base-2 logarithm of e. 

MXOGIOE 

The base-10 logarithm of e. 

MJLN2 . 

The natural logarithm of 2. 

MJLN10 

The natural logarithm of 10. 

MLPI 

7r, the ratio of the circumference of a circle to its diameter. 
(There are also several fractions of n, its reciprocal, and its 
square root.) 

MJ5QRT2 

The positive square root of 2. 

M.SQRT1.2 

The positive square root of 1/2. For the definitions of various 
machine-dependent “constants,” see the description of the 
<t mines.h> header file. 


FILES 


/usr/include/math.h 


SEE ALSO 

intro(3), matherr(3M), values(5). 
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NAME 

prof — profile within a function 



SYNOPSIS 

#define MARK 
^include <prof.h> 

void MARK (name) 


DESCRIPTION 

MARK will introduce a mark called name that will be treated the same as a function 
entry point. Execution of the mark will add to a counter for that mark, and 
program-counter time spent will be accounted to the immediately preceding mark or 
to the function if there are no preceding marks within the active function. 


Name may be any combination of up to six letters, numbers or underscores. Each 
name in a single compilation must be unique, but may be the same as any ordinary 
program symbol. 

For marks to be effective, the symbol MARK must be defined before the header file 
<prof.h> is included. This may be defined by a preprocessor directive as in the 
synopsis, or by a command line argument, i.e: 

cc —p —DMARK foo.c 

If MARK is not defined, the A/AR/£T(name) statements may be left in the source files 
containing them and will be ignored. 


EXAMPLE 

In this example, marks can be used to determine how much time is spent in each 
loop. Unless this example is compiled with MARK defined on the command line, the 
marks are ignored. 

^include <prof.h> 

foo( ) 

int i, j; 


MARK(loopl); 

for (i = 0; i < 2000; i++) { 


MARK(loop2); 

for (j = 0; j < 2000; j++) { 


r 

\ 

^ _ 
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SEE ALSO 

profil(2), monitor(3C). 

prof(l) in the ICON/UXV User Reference Manual. 
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MISCELLANEOUS 


REGEXP(5) 


NAME 

regexp — regular expression compile and match routines 


SYNOPSIS 


lefine INIT <declarations> 
lefine GETC() <getc code> 
lefine PEEKC() <peekc code> 
lefine UNGETC(c) <ungetc code> 
lefine RETURN(pointer) <return code> 
lefine ERROR(val) <error code> 


#include <regexp.h> 


char ^compile (instring, expbuf, endbuf, eof) 
char *instring, *expbuf, *endbuf; 
int eof; 


int step (string, expbuf) 
char *strmg, *expbuf; 


extern char *locl, *loc2, *locs; 
extern int circf, sed, nbra; 


DESCRIPTION 

This page describes general-purpose regular expression matching routines in the 
form of ed( 1), defined in /usr/include/regexp.h. Programs such as ed( 1), 
se</(l), grep( 1), 6s(l), expr(l), etc., which perform regular expression matching use 
this source file. In this way, only this file need be changed to maintain regular 
expression compatibility. 


The interface to this file is unpleasantly complex. Programs that include this 
file must have the following five macros declared before the 
“^include <regexp.h>” statement. These macros are used by the compile rou¬ 
tine. 


GETC() 
PEEKC() 


UNGETC(c) 


RETURN(pointer) 


Return the value of the next character in the regular 
expression pattern. Successive calls to GETC() should 
return successive characters of the regular expression. 

Return the next character in the regular expression. Suc¬ 
cessive calls to PEEKC() should return the same character 
(which should also be the next character returned by 
GETC()). 

Cause the argument c to be returned by the next call to 
GETC( ) (and PEEKC()). No more that one character of 
pushback is ever needed and this character is guaranteed 
to be the last character read bv GETC(). The value of 
the macro UNGETC(c) is always ignored. 

This macro is used on normal exit of the compile routine. 
The value of the argument pointer is a pointer to the 


Icon International, Inc. 


1 



MISCELLANEOUS 


REGEXP (5) 


REGEXP (5) 


ERROR(t>a/) 


ERROR 

11 

16 

25 

36 

41 

42 

43 

44 

45 

46 

49 

50 


character after the last character of the compiled regular 
expression. This is useful to programs which have memory 
allocation to manage. 

This is the abnormal return from the compile routine. 
The argument val is an error number (see table below for 
meanings). This call should never return. 

MEANING 

Range endpoint too large. 

Bad number. 

“\digit” out of range. 

Illegal or missing delimiter. 

No remembered search string. 

\( \) imbalance. 

Too many \(. 

More than 2 numbers given in \{ \}. 

} expected after \. 

'“'irst number exceeds second in \{ \} 

] imbalance. 

Regular expression overflow. 


The syntax of the compile routine is as follows: 
compile(instring, expbuf, endbuf, eof) 


The first parameter instring is never used explicitly by the compile routine but 
is useful for programs that pass down different pointers to input characters. It 
is sometimes used in the INIT declaration (see below). Programs which call func¬ 
tions to input characters or have characters in an external array can pass down 
a value of ((char *) 0) for this parameter. 

The next parameter expbuf is a character pointer. It points to the place where 
the compiled regular expression will be placed. 

The parameter endbuf is one more than the highest address where the compiled 
regular expression may be placed. If the compiled expression cannot fit in 
(endbuf—expbuf) bytes, a call to ERROR(50) is made. 

The parameter eof is the character which marks the end of the regular expres¬ 
sion. For example, in ed( 1), this character is usually a /. 

Each program that includes this file must have a #define statement for INIT. 
This definition will be placed right after the declaration for the function compile 
and the opening curly brace ({). It is used for dependent declarations and ini¬ 
tializations. Most often it is used to set a register variable to point the begin¬ 
ning of the regular expression so that this register variable can be used in the 
declarations for GETC(), PEEKC() and UNGETC(). Otherwise it can be used to 
declare external variables that might be used by GETC(), PEEKC( ) and UNGETC(). 
See the example below of the declarations taken from grep( 1). 

There are other functions in this file which perform actual regular expression 
matching, one of which is the function step. The call to step is as follows: 
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step(string, expbuf) 


The first parameter to step is a pointer to a string of characters to be checked 
for a match. This string should be null terminated. 

The second parameter expbuf is the compiled regular expression which was 
obtained by a call of the function compile. 

The function step returns non-zero if the given string matches the regular 
expression, and zero if the expressions do not match. If there is a match, two 
external character pointers are set as a side effect to the call to step. The 
variable set in step is loci. This is a pointer to the first character that 
matched the regular expression. The variable loc2, which is set by the function 
advance, points to the character after the last character that matches the regu¬ 
lar expression. Thus if the regular expression matches the entire line, loci will 
point to the first character of string and loc2 will point to the null at the end 
of string. 

Step uses the external variable circf which is set by compile if the regular 
expression begins with *. If this is set then step will try to match the regular 
expression to the beginning of the string only. If more than one regular expres¬ 
sion is to be compiled before the first is executed the value of circf should be 
saved for each compiled expression and circf should be set to that saved value 
before each call to step. 

The function advance is called from step with the same arguments as step. The 
purpose of step is to step through the string argument and call advance until 
advance returns non-zero indicating a match or until the end of string is 
reached. If one wants to constrain string to the beginning of the line in all 
cases, step need not be called; simply call advance. 

When advance encounters a * or \{ \> . sequence in the regular expression, it 
will advance its pointer to the string to be matched as far as possible and will 
recursively call itself trying to match the rest of the string to the rest of the 
regular expression. As long as there is no match, advance will back up along 
the string until it finds a match or reaches the point in the string that initially 
matched the * or \{ \}. It is sometimes desirable to stop this backing up 
before the initial point in the string is reached. If the external character 
pointer Iocs is equal to the point in the string at sometime during the backing 
up process, advance will break out of the loop that backs up and will return 
zero. This is used by ed( 1) and sed(l) for substitutions done globally (not just 
the first occurrence, but the whole line) so, for example, expressions like 
s/y*//g do not loop forever. 

The additional external variables sed and nbra are used for special purposes. 


EXAMPLES 

The following is an example of how the regular expression macros and calls look 
from grep( 1): 

^define INIT register char *sp = instring; 

#define GETC() (*sp-H-) 
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#define PEEKC() (*sp) 

#define UNGETC(c) ( sp) 

#define RETURNfc) return: 

^define ERROR(c) regerr() 

^include <regexp.h> 

(void) compile(*argv, expbuf, &expbuf[ESIZE], '\0'); 

if (step(linebuf, expbuf)) 

succeed(); 


FILES 


/usr /include /regexp.h 


SEE ALSO 

bs(l), ed(l), expr(l), grep(l), sed(l) in the ICON/UXV User Reference Manual. 


BUGS 


The handling of circf is kludgy. 

The actual code is probably easier to understand than this manual page. 
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NAME 

stat — data returned by stat system call 


SYNOPSIS 


#include <sys/types.h> 
#include <sys/stat.h> 


DESCRIPTION 

The system calk stat and fstat return data whose structure is defined by this 
include file. The encoding of the field $t_mode is defined in this file also. 


* Structure of the result of stat 

*/ 


struct stat 

dev_t 

st_dev; 

ino_t 

st_ino; 

ushort 

st_mode; 

short 

st_nlink; 

ushort 

st_uid; 

ushort 

st—gid; 

dev_t 

st_rdev; 

off_t 

st_size; 

time_t 

st_atime; 

time_t 

st^mtime; 

time_t 

}; 

st_ctime; 

#define S_IFMT 

0170000 /> 

#define SJFDIR 

0040000 /» 

#define SJFCHR 

0020000 /. 

#define SJFBLIC 

0060000 /■ 

#define SJFREG 

0100000 i 

#define S_IFIFO 

0010000 /■■ 

#define SJSUID 

04000 / 

#define SJSGID 

02000 / 


#define SJSVTX 01000 /* 

#define SJREAD 00400 /* 

#define SJWRITE 00200 /* 

#define SJEXEC 00100 /* 


type of file */ 
directory */ 
character special */ 
block special */ 
regular */ 
fifo */ 

set user id on execution */ 
set group id on execution */ 
save swapped text even after use */ 
read permission, owner */ 
write permission, owner */ 
execute/search permission, owner */ 


FILES 

/usr/include/sys/types.h 

/usr/include/sys/stat.h 
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SEE ALSO 

stat(2), types(5). 
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NAME 

term — conventional names for terminals 


DESCRIPTION 

These names are used by certain commands (e.g., <o6s(l), man(l) and are main¬ 
tained as part of the shell environment (see sh( 1), profile(4), and environ(5)) in 
the variable STERM: 


1520 Datamedia 1520 

1620 DIABLO 1620 and others using the HyType II printer 

1620—12 same, in 12-pitch mode 

2621 Hewlett-Packard 2621 series 

2631 Hewlett-Packard 2631 line printer 

2631—c Hewlett-Packard 2631 line printer - compressed mode 

2631—e Hewlett-Packard 2631 line printer - expanded mode 

2640 Hewlett-Packard 2640 series 

2645 Hewlett-Packard 264n series (other than the 2640 series) 

300 DASI/DTC/GSI 300 and others using the HyType I printer 

300—12 same, in 12-pitch mode 

300s DASI/DTC/GSI 300s 

382 DTC 382 

300s—12 same, in 12-pitch mode 

3045 Datamedia 3045 

33 TELETYPE® Model 33 KSR 

37 TELETYPE Model 37 KSR 

40-2 TELETYPE Model 40/2 

40-4 TELETYPE Model 40/4 

4540 TELETYPE Model 4540 

3270 IBM Model 3270 

4000a Trendata 4000a 

4014 TEKTRONIX 4014 

43 TELETYPE Model 43 KSR 

450 DASI 450 (same as Diablo 1620) 

450—12 same, in 12-pitch mode 

735 Texas Instruments TI735 and TI725 

745 Texas Instruments TI745 

dumb generic name for terminals that lack reverse 
line-feed and other special escape sequences 
sync generic name for synchronous TELETYPE 

4540-compatible terminals 
hp Hewlett-Packard (same as 2645) 

lp generic name for a line printer 

tnl200 User Electric TermiNet 1200 

tn300 User Electric TermiNet 300 

Up to 8 characters, chosen from [—a—zO—9], make up a basic terminal name. 
Terminal sub-models and operational modes are distinguished by suffixes begin¬ 
ning with a —. Names should generally be based on original vendors, rather 
than local distributors. A terminal acquired from one vendor should not have 
more than one distinct basic name. 


Commands whose behavior depends on the type of terminal should accept argu¬ 
ments of the form —T term where term is one of the names given above; if no 
such argument is present, such commands should obtain the terminal type from 
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the environment variable ITERM, which, in turn, should contain term. 


SEE ALSO 


profiled), environ(5). 

man(l), mm(l), nroff(l), tplot(lG), sh(l), stty(l), tabs(l) 
Reference Manual. 


in the ICON/UXV User 


BUGS 


This is a small candle trying to illuminate a. laTge, dark problem. Programs 
that ought to adhere to this nomenclature do so somewhat fitfully. 
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NAME 


types — primitive system data types 


SYNOPSIS 

^include <sys/types.h> 


DESCRIPTION 

The data types defined in the include file are used in ICON/UXV system code; 
some data of these types are accessible to user code: 


typedef 

struct { int rfll; } * physadr; 

typedef 

long 

daddr_t; 

typedef 

char * 

caddr_t; 

typedef 

unsigned int 

uint; 

typedef 

unsigned short 

ushort; 

typedef 

ushort 

ino_t; 

typedef 

short 

cnt_t; 

typedef 

long 

time_t; 

typedef 

int 

label_t[l0l; 

typedef 

short 

dev_t; 

typedef 

long 

off_t; 

typedef 

long 

paddr_t; 

typedef 

long 

key_t; 

form daddr^t is used for 

disk addresses except in an i-node on disk, see 


/s(4). Times are encoded in seconds since 00:00:00 GMT, January 1, 1970. The 
major and minor parts of a device code specify kind and unit number of a dev¬ 
ice and are installation-dependent. Offsets are measured in bytes from the 
beginning of a file. The labeLt variables are used to save the processor state 
while another process is running. 


SEE ALSO 

f«W- 


r 

V..- 


Icon International, Inc. 


1 



VALUES(5) 


MISCELLANEOUS 


VALUES(5) 


NAME 

values — machine-dependent values 


SYNOPSIS 

^include <values.h> 


DESCRIPTION 


This file contains a set of manifest constants, conditionally defined for particular 
processor architectures. The model assumed for integers is binary representation 
(one’s or two’s complement), where the sign is represented by the value of the 
nigh-order bit. 


BITS(type) 

H1BITS 

H1BITL 

HIBITI 

MAXSHORT 

MAXLONG 


The number of bits in a specified type (e.g., int). 

The value of a short integer with only the high-order bit 
set (in most implementations, 0x8000). 

The value of a long integer with only the high-order bit 
set (in most implementations, 0x80000000). 

The value of a regular integer with only the high-order bit 
set (usually the same as HIBITS or HD3ITL). 

The maximum value of a signed short integer (in most 
implementations, 0x7FFF = 32767). 

The maximum value of a signed long integer (in most 
implementations, 0x7FFFFFFF = 2147483647). 


MAXINT The maximum value of a signed regular integer (usually 

the same as MAXSHORT or MAXLONG). 

MAXFLOAT, LN_MAXFLOAT The maximum value of a single-precision 

floating-point number, and its natural logarithm. 

MAXDOUBLE, LN_MAXDOUBLE The maximum value of a double-precision 

floating-point number, and its natural logarithm. 


MINFLOAT, LN_MINFLOAT The minimum positive value of a single-precision 

floating-point number, and its natural logarithm. 


MINDOUBLE, LN_MINDOUBLE The minimum positive value of a double¬ 
precision floating-point number, and its natural 
logarithm. 


FSIGN1F The number of significant bits in the mantissa of a single¬ 

precision floating-point number. 

DSIGNIF The number of significant bits in the mantissa of a 

double-precision floating-point number. 


FILES 


/usr/include/values.h 
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SEE ALSO 

intro(3), math(5). 
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NAME 

varargs — handle variable argument list 


SYNOPSIS 

^include <varargs.h> va_alist va_dcl void va_start(pvar) 
va_list pvar; type va_argfpvar, type) 
va_Ust pvar; void va_ena(pvar) 
va_list pvar; 


DESCRIPTION 

This set of macros allows portable procedures that accept variable argument 
lists to be written. Routines that have variable argument lists (such as 
printj[ 3S)) but do not use varargs are inherently nonportable, as different 
machines use different argument-passing conventions. 

va_alist is used as the parameter list in a function header. 

va_dcl is a declaration for vocalist. No semicolon should follow va_dcl. 

va_list is a type defined for the variable used to traverse the list. 

va_start is called to initialize pvar to the beginning of the list. 

va_arg will return the next argument in the list pointed to by pvar. Type is 
the type the argument is expected to be. Different types can be mixed, but it 
is up to the routine to know what type of argument is expected, as it cannot 
be determined at runtime. 

va_end is used to clean up. 

Multiple traversals, each bracketed by va_start ... va_end, are possible. 


EXAMPLE 

This example is a possible implementation of execl( 2). 
^include <varargs.h> 

#define MAXARGS 100 

/* execl is called by 

execl(file, argl, arg2, ..., (char *)0); 

*/ 

execl(va_alist) 

va_dcl 

va_list ap; 
char *file; 

char *args[MAXARGS]; 
int argno = 0; 
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va_start(ap); \ 

file = va_arg(ap, char *); 

while ((args(argno++] = va_arg(ap, char *)) != (char *)0) 
va_end(ap); 

return execv(file, args); 


SEE ALSO 

exec(2), printf(3S). 


BUGS 


It is up to the calling routine to specify how many arguments there are, since 
it is not always possible to determine this from the stack frame. For example, 
excel is passed a zero pointer to signal the end of the list. Printf can tell how 
many arguments are there by the format. 

It is non-portable to specify a second argument of char, short, or float to 
va_arg, since arguments seen by the called function are not char, short, or float. 
C converts char and short arguments to int and converts float arguments to 
double before passing them to a function. 
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COMMENTS 


ICON/UXV PROGRAMMER REFERENCE MANUAL P/N 172-036-006 


Your comments and suggestions are appreciated and will help us to provide you with the 
very best in system and application documentation. Send your comments to the address at 
the bottom of this page. Users who respond will be entitled to free updates of this manual 
for one year. 

1. How would you rate this manual for COMPLETENESS? (Please Circle) 

Excellent Poor 

5.4.3.2.-.1..0 

2. Is there any information that you feel should be included or removed? 


3. How would you rate this manual for ACCURACY? (Please Circle) 

Excellent 

5.-.4.3.2.-.1. 

4. Indicate the page number and nature of any error(s) found in this manual. 


5. How would you rate this manual for USABILITY? (Please Circle) 


Excellent Poor 

5.— 4.3.2.1 -.0 


6. Describe any format or packaging problems you have experienced with this manual and/or 
binder. 


7. Do you have any general comments or suggestions regarding this publication or future 
publications? 


Poor 
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